mattst88's SkyOS stuff

Button Basics

Everyone understands the importance of buttons in a graphical application, hence it would only be logical that this is one of the most basic things to learn.

First, we'll look at the prototype of GI_WidgetButtonCreate.

HANDLE GI_WidgetButtonCreate (
                HANDLE parent,
                char *  name,
                int     x,
                int     y,
                int     width,
                int     height,
                int     style,
                unsigned int    ID
        )

Parameters:

parent - HANDLE of the Window on which to create the button.
name - Text to be displayed on the button.
x - X coordinate.
y - Y coordinate.
width - Width.
height - Height. Note: This should always be 20, as the default theme does not allow any other values. By specifying something other than 20, one can expect to receive strange results.
style - Style Flags.
ID - ID which is sent to parent when button is pressed. (MSG_COMMAND)

Returns: HANDLE to the new window or NULL.

So to create a Button the code would be:

#define ID_BUTTON 0x01
HANDLE MyButton;
MyButton = GI_WidgetButtonCreate (MainWin, "I'm a Button!", 5, 5, 80, 20, 0, ID_BUTTON);

The #defined number is arbirtary, just note that all IDs must be unique, else the Event Handler won't know how to handle them. Also, catching the HANDLE isn't necessary, but it will allow us to do some other stuff with the button later.

Now that we know how to make a simple button, let's get to the fun stuff: Making buttons do something when they are clicked.

Assuming the button we created earlier is in this same program, the Event Handler code would look something like this:

void EventHandler(HANDLE hWnd, s_gi_msg *msg) {
    switch (msg->type) {                      /* Check for messages */
           case MSG_DESTROY:                  /* If message is MSG_DESTROY: */
                GI_MessageQuitPost(hWnd);     /* Send MSG_QUIT to MainWin */
                break;
           case MSG_COMMAND:                  /* If message is a command: */
                switch (msg->para1) {         /* Check type of message */
                       case ID_BUTTON:
                            MyFunction();
                            break;
                }
           break;
    }
}

Using this code, when the button is clicked, the Event Handler will run MyFunction(). It's as simple as this.

Enabling and Disabling Buttons

Sometimes it's necessary to disable a button and enable it again at a later time. To do this we'll need to call GI_WidgetButtonEnable and GI_WidgetButtonDisable. Here are their prototypes:

int GI_WidgetButtonEnable (HANDLE hWnd) 
int GI_WidgetButtonDisable (HANDLE hWnd)

These are some of the simplest functions to use, as you might be able to see. Just pass the HANDLE of the button you want to enable or disable to the respective function.

Changing a Button's Text

Again, very simple. All we need is GI_WidgetButtonSet.

int GI_WidgetButtonSet (
             HANDLE hWnd,
             char * str
        )

Pass the HANDLE of the button whose text you want to change and the text to change it to.

Button Tooltips

Tooltips are good for better explaining the function of a button. GI_WidgetButtonSetTooltip's prototype is seen below:

HRESULT GI_WidgetButtonSetTooltip (
                 HANDLE          hWnd,
                 char * pText,
                 unsigned int    uiPopupTimeMilliseconds
        )

Pass the HANDLE of the Button, the text to be displayed, and the time it takes for the text to be displayed on mouse over in milliseconds.

The only thing I haven't covered related to Buttons in this document is the use of images (DIBs) as buttons. Maybe I'll do this later.

Related code: buttons.c.