GUI.CreatePictureButton[Full]Part of GUI module

Syntax   GUI.CreatePictureButton (x, y, picture : int,
    actionProc : procedure x ()) : int

GUI.CreatePictureButtonFull (x, y, picture : int,
    actionProc : procedure x (), width, height : int,
    shortcut : char, mergePic : boolean) : int

Description   Creates a picture button and returns the button's widget ID.

Picture buttons behave like buttons (see GUI.CreateButton) except that instead of text on the button, a picture specified by the user is displayed on the button. The picture button widget responds to mouse clicks and keystrokes in the same manner as a regular button widget.

The picture must be created by the program beforehand using Pic.New or Pic.FileNew. The resulting picture can then be used as a parameter to GUI.CreatePictureButton. In general, pictures should be a maximum of about 50 pixels high and wide, although there is no built-in limit in the GUI library.

The x and y parameters specify the lower-left corner of the picture button. The picture parameter specifies the picture ID of the picture to be displayed on the button. (Note that, in general, this picture should be fairly small.) The picture ID is received from a Pic.New or Pic.FileNew call. Do not call Pic.Free for this picture ID until the button has been disposed of by calling GUI.Dispose. The actionProc parameter specifies the name of a procedure that is called when the picture button is pressed.

For GUI.CreatePictureButtonFull, the width and height parameters specify the width and height of the button. If they are set to 0, then the picture radio button is automatically sized to fit the picture. If you need to know the precise size of the button, use the GUI.GetWidth and GUI.GetHeight functions. If width and height are larger than the picture, the picture is centered in the button. The shortCutparameter is the keystroke to be used as the button's shortcut. The mergePic parameter specifies whether anything that was the background colour in the picture (usually colour 0) should be set to the background colour of the button (which is usually gray). This defaults to true for CreatePictureButton.

Two Picture Buttons

Example   The following program displays five picture buttons which output a message when pressed.

        import GUI
        View.Set ("graphics:100;70") 
        
        const size : int := 25   % The buttons size.
        const border : int := 3
        
        var starButton, mapleButton, starPic, mapleLeafPic : int
        
        procedure StarPressed
            Text.Locate (1, 1)
            put "Star Pressed    "
        end StarPressed
        
        procedure MaplePressed
            Text.Locate (1, 1)
            put "Maple Pressed "
        end MaplePressed
        
        % Create the pictures.
        % The star.
        Draw.Star (border, border, border + size, border + size, black)
        Draw.Star (border + 1, border + 1, border + size - 1,
            border + size - 1, black)
        Draw.FillStar (border + 2, border + 2, border + size - 2,
            border + size - 2, brightred)
        starPic := Pic.New (0, 0, 2 * border + size, 2 * border + size)
        
        % The mapleleaf.
        Draw.FillBox (border, border, border + size, border + size, white)
        Draw.MapleLeaf (border, border, border + size, border + size, black)
        Draw.MapleLeaf (border + 1, border + 1, border + size - 1,
            border + size - 1, black)
        Draw.FillMapleLeaf (border + 2, border + 2, border + size - 2,
            border + size - 2, brightred)
        mapleLeafPic := Pic.New (0, 0, 2 * border + size, 2 * border + size)
        
        % Create the picture buttons.
        Draw.Cls
        starButton := GUI.CreatePictureButton (10, 10, starPic, StarPressed)
        mapleButton := GUI.CreatePictureButton (55, 10, mapleLeafPic, 
            MaplePressed)
        
        loop
            exit when GUI.ProcessEvent
        end loop

Execute  

Details   When GUI.CreatePictureButton or GUI.CreatePictureButtonFull is called, the newly created picture will be displayed immediately unless GUI.DisplayWhenCreated has been called with the display parameter set to false.

When a picture button is not enabled, the picture button is grayed out and the picture button no longer responds to any mouse clicks or keystrokes until the button is enabled again.

Details   The following GUI subprograms can be called with a picture button as the widgetID parameter:

 GUI.Show, GUI.Hide, GUI.Enable, GUI.Disable, GUI.Dispose, GUI.GetX, GUI.GetY, GUI.GetWidth, GUI.GetHeight, GUI.SetPosition, GUI.SetSize, GUI.SetPositionAndSize

Status   Exported qualified.

This means that you can only call the function by calling GUI.CreatePictureButton, not by calling CreatePictureButton.