minigui-docs/programming-guide/MiniGUIProgGuidePart1Chapter09.md

Icon, Cursor, and Caret

Icon

An icon is a small image, and is usually used to present an application, or used in the windows such as warning message box. It consists of a bitmap and a mask bitmap, and can produce transparent image region. An icon file may include more than one icon image, and the application can choose an appropriate one to use according to the size and color bit number of each icon image.

MiniGUI provides the support to load, display, create and destroy of mono-color, 16-color and 256-color Windows icons.

Loading and Displaying Icon

The application can use the LoadIconFromFile function to load an icon file, and the prototype of the LoadIconFromFile function is as follows:

The argument meanings are as follow:

• hdc: The device context.
• filename: The file name of the icon file
• which: The index value of the selected icon.

LoadIconFromFile function loads an icon from a Windows icon file (*.ico), and the icon can be mono-color, 16-color or 256-color icon. Some Windows icon files contain two icons in different sizes. You can tell this function to load which icon though the argument of which, 0 for the first icon, and 1 for the second icon. LoadIconFromFile function reads in the information of the icon size, color bit number and bitmap image pixel data, etc., calls CreateIcon function to create an icon object, and then returns an icon handle which presents the loaded icon object.

You can also load an icon from a memory area by LoadIconFromMem function, the prototype of which is as follows:

The memory area pointed to by area must have the same layout as a Windows ICO file.

After the application has loaded the icon object, you can call DrawIcon function to draw an icon in the specified position. DrawIcon function draws an icon object in a rectangle region. The prototype of DrawIcon function is as follows:

The argument meanings are as follow:

• hdc The device context.
• x, y The x and y coordinates of the upper-left corner of the rectangle.
• w, h The width and height of the rectangle, respectively
• hicon The handle of the icon object.

The code in List 1 illustrates how to load an icon from an icon file, and then draw an icon in the client area of the window. The complete code of this program can be referred to program drawicon.c in sample program package mg-samples for this guide.

List 1 Loading and drawing an icon

The output of the program is as shown in Figure 1.

Figure 1 Drawing icon

The program described above loads two 16-color icons of 32x32 pixels and 16x16 pixels, respectively. The icon with number 0 is the big icon with 32x32 pixels, and is saved in the icon object myicon_large; and the icon with number 1 is the small one with 16x16 pixels, and is saved in the icon object myicon_small. The program uses DrawIcon function to draw these two icons in the client area of the window when handling MSG_PAINT message. Note that w and h arguments passed to DrawIcon function are both zero when calling it, and in this case DrawIcon function will draw the icon according to its original size without scaling.

Destroying Icon

The application should destroy an icon when the application does not need it any more. The program above destroys the two icons previously loaded using LoadIconFromFile function by calling DestroyIcon function when it is going to quit (when handling MSG_CLOSE message). DestroyIcon function destroys the icon handle, and releases the memory it used. This function’s prototype is as follows:

DestroyIcon function has only one parameter hicon, which specify the icon object to be destroyed. The icon loaded by LoadIconFromFile function needs to be destroyed by DestroyIcon function. We will see that DestroyIcon can also destroy the icon created dynamically by the application using CreateIcon function.

Creating Icon

Besides loading an icon from an icon file, the application can also use CreateIcon function to create an icon dynamically at run time. The icon created by this function also needs to be destroyed by calling DestroyIcon function. The prototype of CreateIcon function is as follows:

The argument meanings are as follow:

CreateIcon creates an icon according to the specified data such as icon size, color and the bit-mask bitmap image. The icon width and height specified by arguments of w and h respectively must be sizes supported by the system, for example 16x16 pixels or 32x32 pixels. PAndBits points to a byte array, which comprises the image data of the AND bit-mask bitmap of the icon, and the AND bit-mask bitmap should be mono-color. PXorBits points to a byte array, which comprises the image data of the XOR bit-mask bitmap of the icon, and the XOR bit-mask bitmap can be a mono-color or colorful. MiniGUI currently supports mono-color icon, 16-color icon and 256-color icon. Colornum specifies the number of color bits of the icon, i.e., the number of the color bits of the XOR bit-mask bitmap. For mono-color icon, it should be 1, for 16-color icon, it should be 4, for 256-color icon, it should be 8.

The code in List 2 describes how to use CreateIcon function to create a user-defined icon during runtime. The complete code of this program is available in program createicon.c in the example program package mg-samples.

List 2 Creating an icon

The output of the program is as shown in Figure 2.

Figure 2 Creating and drawing icon

The code in List 2 creates a user-defined icon new_icon by calling CreateIcon according to the data in the ANDmaskIcon and XORmaskIcon bit-mask byte array. The size of the icon is 16x16 pixels, and the number of color bits is 4. And then the program draws the created “interrogation” icon in the client area of the window with its original size and scaled size. Finally, the program calls DestroyIcon function to destroy the user-defined icon created by CreateIcon function when handling MSG_CLOSE message.

Using System Icons

Each renderer section in MiniGUI.cfg, the configuration file of MinGUI, defines the icons which are used and provided by the system. The icons of Classic renderer are shown as follow:

NOTE The maximum number of the icon files the system uses is 5, which is defined in the source code of MiniGUI. Therefore, if you modify the iconnumber item in the configuration file, its value should be smaller than or equal to 5, and the icons with number larger than 5 will be ignored.

There are four renderers are defined in MiniGUI.cfg, the configuration file of MiniGUI, classic, flat, skin and fashion (fashion renderer must be together with mgplus component). Each renderer defines the specified system icons. MiniGUI loads all the system icons from icon files to memory according to the setting of the iconinfo section in the configuration file when initializing renderer. The application can get the built-in system icons through GetLargeSystemIcon function and GetSmallSystemIcon function. The prototypes of these two functions are as follow:

GetLargeSystemIcon is used to get a large system icon with 32x32 pixels, and GetSmallSystemIcon is used to get a small system icon with 16x16 pixels. These two functions return the handle of the built-in system icon object. The obtained icon is one of the seven system icons, which is specified by id. Id is an integer value, and may be one of the following values:

These identifiers are defined in minigui/window.h as follow:

It can be seen that they present the five icon files with sequence number from 0 to 4 in MiniGUI.cfg. The icon files with index numbers 5 and 6 are used by TREEVIEW control.

The icons obtained by GetLargSystemIcon and GetSamllSystemIcon functions are system-predefined icons, which are system sharing resources and do not need to be destroyed by the application.

In addition, the application may also use LoadSystemIcon function to load the required icon directly from the icon file defined in MiniGUI.cfg configuration file:

Here szItemName argument specifies the symbol name of the icon file defined in the iconinfo section of MiniGUI.cfg, for example, icon0 presents form.ico icon file. The argument of which specifies which icon is to be loaded. This function returns the handle to the obtained icon object.

Actually, LoadSystemIcon loads an icon by calling LoadIconFromFile. Apparently, the icon created by LoadSystemIcon must be destroyed using DestroyIcon function when it is not be required any more.

Cursor

The pointing device such as mouse controls a cursor, which is a small bitmap and its position in the screen. It is used to indicate the position of the pointing device. When the user moves the mouse, the cursor will move on the screen accordingly. If the cursor moves into different region or different window, the system possibly changes the shape of the cursor. A pixel called hotspot in the cursor indicates the accurate position of the cursor on the screen. The system uses this point to trace and identify the cursor position. For example, the hotspot of a arrow cursor is commonly its arrowhead position. The cursor hotspot is commonly the cursor focus. If a mouse input event occurs, the system will send the mouse containing the hotspot coordinates to the window, which the hotspot is located in, or to the window, which captures the mouse.

MiniGUI provides functions for loading, creating, displaying, destroying, and moving mono- and 16-color cursors. Currently, MiniGUI does not support 256-color or animation cursor.

Loading and Creating Cursor

The application may use LoadCursorFromFile function to load a cursor form a Windows cursor file. The prototype of this function is as follows:

LoadCursorFromFile function reads in information of the size of the cursor, the hotspot position, the number of color bits, and the bitmap image data, etc., creates an cursor object, and returns a cursor handle presenting this cursor object.

LoadCursorFromMem function loads a cursor from memory:

This function loads a cursor from a specified memory area, the cursor memory area to which area points should be the same as the layout of the Windows cursor file.

The application may also create dynamically a cursor by calling CreateCursor function during run time. The prototype of CreateCursor function is as follows:

The argument meanings are as follow:

Similar to the method of creating an icon by CreateIcon function, CreateCursor function creates an cursor according to the data of specified cursor size, color and bit-mask bitmap image in memory. The difference is that the hotspot position of the cursor to be created must be specified when using CreateCursor function. Xhotspot and yhotspot arguments specify the horizontal and vertical positions of the hotspot of the created cursor, respectively. The cursor width and height specified by w and h must be the size supported by the system, and MiniGUI can only use cursor of 32x32 pixels. Therefore, the value of w and h arguments can only be 32. PANDBits points to a byte array of a AND bit-mask bitmap image data containing a cursor, and AND bit-mask bitmap is a mono-color bitmap. PXorBits points to a byte array of a XOR bit-mask bitmap image data containing a cursor, and XOR bit-mask bitmap may be either a mono-color bitmap or a color bitmap. Colornum specifies the number of color bits of the cursor, or the number of color number of the XOR bit-mask bitmap. For a mono-color cursor, it should be 1, and for 16-color cursor, it should be 4.

Destroying Cursor

The application should destroy the cursor when not requiring it any more. DestroyCursor function can destroy the cursor created by LoadCursorFromFile and CreateCursor functions, and release the memory used by the cursor object. The prototype of this function is as follows:

The argument hcursor of DestroyCursor function specifies the cursor object to be destroyed.

Positioning and Displaying Cursor

If the system includes a mouse, then the system will display it automatically, and update its position on the screen according to the position of mouse and repaint the cursor. The application can get the current screen position of the cursor by calling GetCursorPos function, and move the cursor to the specified position on the screen by calling SetCursorPos function.

The application can get the current cursor handle by calling GetCurrentCursor function, and set the current cursor by calling SetCursorEx function. The prototypes of these two functions are as follow:

SetCursorEx function sets the cursor specified by hcsr as the current cursor. If set_def is TRUE, SetCursorEx will further set this cursor as the default cursor, which is the cursor displayed when moved the mouse to the desktop. This function returns old cursor handle. SetCursorEx has other two simplified versions: SetCursor and SetDefaultCursor. SetCursor sets the current cursor and does not change the default cursor; and SetDefaultCursor sets the specified cursor as the current cursor and the default cursor.

MiniGUI will send MSG_SETCURSOR to the window under the cursor when the user moves the mouse, and the application can change the current cursor when handling MSG_SETCURSOR message. If the window procedure function changes the cursor when handling this message, it should be returned immediately.

The system displays the class cursor related to the control where the cursor is. The application can assign a class cursor to the control class when registering the control class. After registering this control class, each control of this control class has the same class cursor, i.e., the cursor displayed by the system is the same specified cursor when the mouse moves onto these controls. The application can get the current cursor of the specified window through GetWindowCursor, and sets a new window cursor through SetWindowCursor.

The code below is from listview.c in the MiniGUI source code, which illustrates how to assign a cursor handle to hCursor member of the WNDCLASS structure to specify the class cursor for a control class.

The class cursor in the code above is the system default cursor gotten by GetSystemCursor function, i.e., an arrow cursor. GetSystemCursor (0) and GetSystemCursor (IDC_ARROW) are the same.

The application can show or hide the cursor by calling ShowCursor function.

ShowCursor function hides the cursor when parameter fShow is FALSE, and shows the cursor when fShow is TRUE. ShowCursor does not change the shape of the current cursor. This function internally uses a cursor showing counter to determine whether showing or hiding the cursor. Each calling of ShowCursor function to show the cursor will increase this counter by one, and each calling of ShowCursor function to hide the cursor will decrease this counter by one. The cursor is visible only when the counter is larger than or equal to 0.

Clipping Cursor

The application can use ClipCursor function to clip the cursor within a certain rectangle area, which is usually used to correspond to an event in a certain clipping rectangle. The prototype of this function is as follows:

The specified clipping rectangle is pointed by parameter prc. If prc is NULL, ClipCursor will disable cursor clipping. When ClipCursor function clips the cursor in a certain rectangular area on the screen, it moves the cursor to the center of the rectangular area.

GetClipCursor function gets the current cursor clipping rectangle, and can be used to save the original clipping rectangle before setting a new clipping rectangle and use it to restore the original area when required. The prototype of this function is as follows:

Using System Cursors

The cursorinfo section in the configuration file of MiniGUI, MiniGUI.cfg, defines all the cursors provide by the system, as shown below:

The maximum number of the cursors used by the system defined in MiniGUI is (MAX_SYSCURSORINDEX + 1). MAX_SYSCURSORINDEX is the maximum system cursor index value, defined as 22; therefore the maximum cursor number predefined by the system is 23.

MiniGUI loads all the system cursors from the specified cursor files to memory according to the setting of the cursorinfo section in the configuration file when initializing the system. The application can get the built-in system cursor through GetSystemCursor function. The prototype of this function is as follows:

GetSystemCursor function returns the handle to the cursor object in memory. The obtained cursor is one of the possible 23 system system-predefined cursors, and is specified by identifier csrid. Parameter csrid is an integer value, and may be one of the following values:

The definitions of these cursor index values are as follow:

They present the 23 system-predefined cursors with sequence number from 0 to 22 in MiniGUI, respectively.

The cursor gotten through GetSystemCursor function is the system-predefined cursor, and belongs to the system sharing resource; therefore it needs not to be destroyed by the application.

Sample Program

The code in List 3 illustrates the use of the cursor in MiniGUI. The complete code of this program is available in program cursordemo.c in the sample program package mg-samples.

List 3 Using cursor

Figure 3 Using cursor

The user interface of the sample program above is shown in Figure 3. The procedure of the main window registers a window class “trap” by calling RegisterTrapWindow function, and then creates a child window of “trap” class with size of 100x100 in the up-left corner (10, 10). RegisterTrapWindow function sets the background color of the window to be black and sets the window class cursor to be hand-point cursor when registering the “trap” window class. The window procedure of trap window class clips the cursor within this window by calling ClipCursor function when handling MSG_MOUSEMOVE message.

When handling MSG_LBUTTONDOWN message, the main window procedure first gets the main window rectangle by calling GetWindwoRect, clips the cursor within the main window rectangle by calling ClipCursor function, and then hides the cursor by calling ShowCursor function. When handling MSG_RBUTTONDOWN message, the main window procedure shows the cursor by calling ShowCursor function. The main window procedure resets the current cursor (arrow cursor) to I-shaped cursor.

During program running, the moving of the cursor is clipped within the main window and is hidden when the user clicks the mouse left button in the main window. The user can show the cursor again by clicking the right mouse button. When the cursor is moved onto the trap window, it will be “grasped” within this black window.

Caret

The caret is a blinking character in the window client area, and is normally used to indicate the position of keyboard input. Usual shapes of the caret are an underline, a vertical line, a block, and so on.

MiniGUI provides the application with functions of creating, destroying, showing, hiding, positioning the caret, and changing the caret blinking time.

Creating and Destroying Caret

CreateCaret function creates a caret and assigns it to a specified window.

The argument meanings are as follow:

If pBitmap is not NULL, CreateCaret function will create a caret according to the bitmap object. If pBitmap is NULL, CreateCaret function will create the caret by a rectangle with nWidth wide and nHeight high. The width nWidth and height nHeight of the caret are in pixels.

The caret is hidden after being created. To show the caret, you must call ShowCaret function to show the caret on the screen after creating it by calling CreateCaret function.

DestroyCaret function destroys the caret created by CreateCaret function, and its prototype is as follows:

DestroyCaret function destroys the caret of a window, and deletes it from the screen.

We can create a caret by calling CreateCaret in MSG_CREATE message, and then destroy it by calling DestroyCaret function when receiving MSG_DESTROY message.

Showing and Hiding Caret

At a time, only one window has the keyboard input focus. Usually, the window, which receives the keyboard input, shows the caret when receiving the input focus, and hides the caret when losing the input focus.

The system sends MSG_SETFOCUS message to the window that has received the input focus and the application should shows the caret by calling ShowCaret function when receiving this message. When the window loses the keyboard input focus, the system sends a MSG_KILLFOCUS message to this window, and the application should hides the caret by calling HideCaret function when handling this message. The prototypes of these two functions are as follow:

ShowCaret function shows the caret of a given window, and the caret will automatically blink after appearing. HideCaret function deletes the caret from the screen. If the application must repaint the screen when handling MSG_PAINT message, and must retain the caret, you can use HideCaret function to hide the caret before painting, and use ShowCaret function to show the caret again after painting. If the message being handled by the application is MSG_PAINT message, you need not hide and show again the caret, because BeginPaint and EndPaint function will automatically finish these operations.

Positioning Caret

The application uses GetCaretPos function to get the position of the caret, and uses SetCaretPos function to move the caret within a window.

The function GetCaretPos copies the position of the window caret, in client coordinates, to a POINT structure pointed to by pPt. SetCaretPos function moves the caret of the window to the position in the client area specified by x and y, regardless whether or not the caret is visible.

Changing Blink Time of Caret

The elapsed time for reversing the caret is called reversing time. Blinking time is referred to the elapsed time for showing, reversing, and recovering. The application uses GetCaretBlinkTime to get the blink time of the caret, in milliseconds. The blink time of the system default caret is 500 milliseconds. You can use SetCaretBlinkTime function to change the blink time of the caret. The blink time of the caret cannot be less than 100 milliseconds. The definitions of these two functions are as follow:

Sample Program

The code in List 4 uses the caret functions discussed in this section to create a simple text input window, which can be considered as a simple edit box control. In “myedit” control, you can input less than 10 characters, move the caret by left and right arrow key (caret moving key), and delete the character in the window with backspace key. The complete code of this program is available in program caretdemo.c in the sample program package mg-samples.

List 4 Using caret

Figure 4 A simple edit box

For simplification, we use fixed-width font in “myedit” because other fonts are more difficult to handle. The window procedure function of myedit uses GetSystemFont (SYSLOGFONT_WCHAR_DEF) to get the system default fixed-width font, and then set the font of the text input window by calling SetWindowFont. Myedit control calls CreatCaret function in MSG_CREATE message to create a caret of width 1 and the same height as the font.

The buffer area pointed to by pBuffer is used to save the characters input into the text window; len presents the number of characters, and pos presents the current edit position of the current caret.

The window procedure of myedit calls ShowCaret function to show the caret when receiving MSG_SETFOCUS message, and calls HideCaret to hide the caret when receiving MSG_KILLFOCUS message.

myedit handles the input of normal characters in MSG_CHAR message, and adjusts the buffer and values of the pos and len correspondingly. Furthermore, each time myedit receives special character such as newline, myedit calls SetCaretBlinkTime to reduce the reversing time of caret by 100 ms.

myedit handles the left and arrow keys and the backspace key in MSG_KEYDOWN message, adjusts the caret position by calling SetCaretPos function, paints in MSG_PAINT, and destroys the caret when receiving MSG_DESTROY message.

<< Input Messages | Table of Contents | Look-and-feel and UI Effects >>

[Writing DRI Engine Driver for Your GPU]: /supplementary-docs/Writing-DRI-Engine-Driver-for-Your-GPU.md [Writing MiniGUI Apps for 64-bit Platforms]: /supplementary-docs/Writing-MiniGUI-Apps-for-64-bit-Platforms.md

[Building MiniGUI]: /user-manual/MiniGUIUserManualBuildingMiniGUI.md [Compile-time Configuration]: /user-manual/MiniGUIUserManualCompiletimeConfiguration.md [Runtime Configuration]: /user-manual/MiniGUIUserManualRuntimeConfiguration.md [Tools]: /user-manual/MiniGUIUserManualTools.md [Feature List]: /user-manual/MiniGUIUserManualFeatureList.md