GRIDPLUS2 - Button Grid
Home Reference Manpage Examples Download License Contact

GRIDPLUS Button Grid

In order to simplify creation of screen layouts, GRIDPLUS provides a GRIDPLUS button command mode. This command mode is a "short cut" method to invoke the GRIDPLUS widget command mode with the default widget set create buttons. All of the normal widget command mode functionality can be used. For example creating other widget types. If the ICONS package is installed, the buttons may have icon images instead of text. This can be used as simple method to create toolbars.

This uses a simple syntax to create a grid of checkbuttons. The syntax is closely based on the GRIDPLUS Grid and Widget.

GRIDPLUS Button Specific Item Options/Functionality

See GRIDPLUS Widget Grid for a full list of item options/functionality.

+
Specifies that the button should have keyboard focus.

.proc=parameter
The name of the widget. This is an optional way to define a widget name for buttons. Using the example: .myproc=myparameter, the widget will be called ".myproc=myparameter", the procedure called when the button is pressed will be "myproc" to which will be passed a parameter, in this case "myparameter".

!
Specifies that entry validations are to be perfomed (for the window containing the button) prior to evaluating the command.

!+
Indicates that entry validations are to be perfomed (for the window containing the button) prior to evaluating the command. Additionally, if an entry loses focus to the button, the validation for the entry losing focus will be performed first.

~
Specifies the name of a command to be invoked when a button is pressed. The default is for the command name to be based on the name of the widget (See below).

integer
Specifies a positive integer which overrides the default width for the button.

Note: When specifying buttons with icons make sure that the .widget name appears before :icon name - Otherwise spurious label widgets are created.

Name of Command Invoked When Button is Pressed

By default the name of the command invoked when a button is pressed is based on the name of the toplevel (if appropriate), the grid which contains the button and the button ID.

grid,button_id
...or...
toplevel:grid,button_id

gridName of grid without leading dot.
toplevelName of toplevel window without leading dot.
button_idButton ID without leading dot.

Examples assuming a button with ID ".saveperson" in grid ".actions":-

Main/Root Window:actions,saveperson
Toplevel Window:mywindow:actions,saveperson

Note: It is possible to override the default by explicitly specifying the name of a command by using the ~command widget option.

Examples

This section contains a number of examples which illustrate the main GRIDPLUS button command mode features.

The following examples assume that the reader is familiar with the contents of the Grid/Layout and Widget pages. Information given on that page will not be duplicated here.

Note: All examples assume that the GRIDPLUS package has already been "required" and the commands imported.


Button Example 1

Window:

Source Code:

gridplus button .mygrid1 -title "My Grid 1" {
  {"Button 1" .mybutton1} {"Button 2" .mybutton2} {"Button 3" .mybutton3}
  {"Button 4" .mybutton4} {"Button 5" .mybutton5} {"Button 6" .mybutton6}
  {"Button 7" .mybutton7} {"Button 8" .mybutton8} {"Button 9" .mybutton9}
}

gridplus button .mygrid2 -title "My Grid 2" {
  {"Button 1" .mybutton=myparm1}
  {"Button 2" .mybutton=myparm2}
  {"Button 3" .mybutton=myparm3}
  {"Button 4" .mybutton=myparm4}
}

gridplus button .mygrid3 -title "My Grid 3" {
  {"Button 1" .mybutton1} {"Button 2" .mybutton2}
}

gridplus layout .main -wtitle "Button Example" {
   .mygrid1:ns .mygrid2
   .mygrid3:ew -
}

pack .main

Comments:

This example is based on Grid/Layout Example 2. Here, however, three Grids contains buttons are created.

When using the GRIDPLUS button command mode the "label" defines the text that will appear on the button. Separate labels are not created for this command. The cell item begining with a dot is the widget (button) ID. The buttons are created with names based on the name of the containing Grid and the widget ID.

For example: The for the ".mygrid1" cell defined by "{"Button 2" .mybutton2}" a button widget is created with the name ".mygrid1,mybutton2". Please note that the widget name does contain a comma - this is not a misprint!!

When the button is "pressed" (By default) a command with a name based on that of the widget is invoked. In the case of the "{"Button 2" .mybutton2}" example the command is called "mygrid1,mybutton2".

The buttons in ".mygrid2" use a different format for the widget ID.

For example: The for the ".mygrid2" cell defined by "{"Button 1" .mybutton=myparm1}" a button widget is created with the name ".mygrid2,mybutton=myparm1". When the button is "pressed" the command invoked is based on the part of the widget name before the "=". In this case "mygrid2,mybutton". The part of the widget name after the "=" is passed as a paramter to the command. In this case "myparm1"


Button Example 2

Window:

Source Code:

gridplus button .toolbar -space 0 -padding 0 -style Toolbutton {
 {.back :navback16 ?Back} {.forward :navforward16 ?Forward} {.home :navhome16 ?Home} | \
 {.reload :actreload16 ?Reload} {.stop :actstop16 ?Stop} | {.exit :actexit16 "?Exit Application"}
}

gridplus button .mygrid1 -title "My Grid 1" {
  {"Button 1" .mybutton1} {"Button 2" .mybutton2} {"Button 3" .mybutton3}
  {"Button 4" .mybutton4} {}                      {"Button 6" .mybutton6}
  {"Button 7" .mybutton7} {"Button 8" .mybutton8} {"Button 9" .mybutton9}
}

gridplus button .mygrid2 -width 10 -title "My Grid 2" {
  {"Button One"   .mubutton1}
  {"Button Two"   .mybutton2}
  {"Button Three" .mybutton3}
  {"Button Four"  .mybutton4}
}

gridplus layout .main -pady 2 -wtitle "Button Example" {
   .toolbar     -
   =            -
   .mygrid1:ns  .mygrid2
}

pack .main

Comments:

This example demonstrates creating a toolbar by using a Button Grid. If the ICONS package is installed, GRIDPLUS can easily create buttons with icon images.

".toolbar" contains a row of icon buttons. Icon buttons do not have button (label) text, instead the name of the ICONS package icon is specified with a colon (":") prefix. The widget (button) ID is optional (See below).

All buttons can have optional pop-up/balloon help. This is mostly applicable when using icon button to create a toolbar. The help text (if required) is specified a string starting with a question mark ("?"). If the string is to contain more than one word it must be enclosed within double quotes - Note: the question mark must be inside the quotes.

To create an Icon button it is only neccessary to specify an icon. In which case the command invoked by the button would be based on the name of the button Grid and the name of the icon.

For Example: "{:navback16 ?Back}".

In this case the widget would be called ".toolbar,navback16" and the command invoked when the button is pressed would be "toolbar,navback16".

However, in this example a widget Identifier (begining with a dot (".") is also specified to explicitly define the name of the widget and the command invoked when the button is pressed.

For Example: "{.back :navback16 ?Back}".

".back" is the widget Identifier. ":navback16" is the name of the icon from the ICONS package.

In this case the widget would be called ".toolbar,back" and the command invoked when the button is pressed would be "toolbar,back".

The rest of the items are for options specific to the button. The vertical bar ("|") can be used in place of a widget to create a separator bar.

In ".toolbar" the -space 0 option is set. This causes the buttons to butt together (No space between the buttons). The -padding 0 option is also set. This reduces the gap between the buttons and the edges of the enclosing Layout.


Copyright © 2013 Adrian Davis.