FvwmGtk1

Usage

Overview

The FvwmGtk module implements GTK-based alternatives to the GUI elements in fvwm, namely the builtin menus and the FvwmForm dialogs.

Invocation

No command line invocation is possible. FvwmGtk must be invoked by the fvwm window manager. When invoked with the optional name argument, name is used to find configuration commands and configuration files instead of "FvwmGtk".

Options

FvwmGtk only has options to define the content of the menus and dialogs. This includes the labels and pixmaps to show; configuration of the appearance must be done through the GTK rc file mechanism.

FvwmGtk gets config info from fvwm's module configuration database (see fvwm(1), section MODULE COMMANDS) when it starts up. In addition, FvwmGtk accepts commands from fvwm and its modules as it runs.

If the optional name is used to start FvwmGtk, name is used in all commands, messages, menus and forms generated by FvwmGtk and in the configuration file name. Unlike other fvwm modules, there is little reason to use the optional name.

All dialogs and menus have to be defined through configuration commands before they can be used. A dialog or menu is invoked by sending its name to FvwmGtk. For menus, you also send the button which is to be used.

	SendToModule FvwmGtk menu-example 1
	SendToModule FvwmGtk dialog-example

Menus

The following commands define menus. For all arguments named "label" in the following menu commands, FvwmGtk looks for embedded ampersands in the same way fvwm does for its menus.

*FvwmGtk: Menu name

Instructs FvwmGtk to append subsequent items to the menu named by the argument. Note that you can "reopen" a menu and continue to append to it. It is also possible to redefine a menu from scratch, see *FvwmGtk: Destroy.

*FvwmGtk: Title label [ icon [ r_label ] ]

Appends a title to the currently open menu. If the optional argument is given, it should be the name of an xpm file in the ImagePath. The icon will appear to the left of the text. If FvwmGtk has been compiled with imlib support, icon can of any image format imlib can read. The label can contain an ampersand to mark the following character as an accelerator to be underlined. Underlined accelerators work in the same way as they do in fvwm native menus. If r_label is given, it will be right-justified.

*FvwmGtk: Item label action [ icon [ r_label ] ]

Appends an item to the currently open menu. The first argument is the text that will appear in the item, the second argument will be sent to fvwm when the item is activated. If the optional argument is given, it should be the name of an xpm file in the ImagePath. The icon will appear to the left of the text. The label can contain an ampersand to mark the following character as an accelerator to be underlined. Underlined accelerators work in the same way as they do in fvwm native menus. If r_label is given, it will be right-justified.

*FvwmGtk: Submenu label name [ icon ]

Appends an item to the currently open menu. The first argument is the text that will appear in the item, the second argument is the name of the sub menu that will be opened when the item is selected. If the sub menu doesn't exist yet, it will be created. If the optional argument is given, it should be the name of an xpm file in the ImagePath. The icon will appear to the left of the text. The label can contain an ampersand to mark the following character as an accelerator to be underlined. Underlined accelerators work in the same way as they do in fvwm native menus.

*FvwmGtk: Tearoff

Appends a special tear-off item. Activating it turns the menu into a permanent window; activating it once more makes the menu disappear again.

Window lists

Window lists are special dynamically created menus. They offer a list of all windows managed by fvwm and send "WindowListFunc" back to fvwm within the window context of the selected window. WindowListFunc is the same function that is also used by fvwm for its builtin window list.

*FvwmGtk: WindowList name [ option... ]

Creates a window-list bound to name. The window-list will be formatted according to the given options. Currently supported are the following options which have the same meaning as for the fvwm's builtin window list: "NoGeometry", "NoMiniIcon", "UseIconName", "Desk <desk>", "CurrentDesk", "Icons/NoIcons/OnlyIcons", "Sticky/NoSticky/OnlySticky", "Normal/NoNormal/OnlyNormal", "NoDeskSort", "Alphabetic", "Function <func>". The following options are new: "Title <label> <icon> <r_label>". Additionally, you can specify a name pattern to match the name or icon name of the listed windows.

Dialogs

Dialogs consist of hierarchically organized widgets. Widgets are either composite, ie they can contain one or more other widgets, or atomic. Composite widgets are defined by a pair of commands denoting the start and end of the list of child widgets. Atomic widgets are defined by single commands. Some widgets request data from the user. These are all given names which can be used to refer to the data.

The commands for widgets have the common form:

*FvwmGtk: Widget widget-specific args [ -- general-args ]

where the following arguments may be specified after the double hyphen: can-default, default, focus, expand, fill and an integer argument padding.

can-default means that the widget may become the default widget of the dialog (ie the one being activated if the user immediately presses Return).

default means that the widget is the initial default widget.

focus means that the widget initially has the keyboard focus.

expand, fill, padding are relevant if the widget is part of a row or column (see the GTK documentation).

The following paragraphs explain only the widget-specific arguments.

*FvwmGtk: Dialog name title [ center ]

Starts or reopens a dialog named by the first argument. title is used as the window title. If the optional argument center is given, the dialog will be mapped at the center of the screen. Otherwise it will be mapped at the mouse position.

A dialog has one child widget.

*FvwmGtk: Box [ vertical ] [ homogeneous ] [ spacing [ border ] ]

*FvwmGtk: EndBox

Start and end a composite widget which is used to group a number of child widgets in a row or column. The arguments influence the placement of the child widgets (for information about their meaning, see the GTK documentation).

*FvwmGtk: Frame label [ border ]

*FvwmGtk: EndFrame

Start and end a composite widget which draws a frame labeled by the given label around a single child widget. The optional argument determines the separation between the frame and the child.

*FvwmGtk: Label label

Adds a label widget.

*FvwmGtk: Entry name [ initial-value ]

Adds a widget which allows the user to enter a string. If given, the initial-value is displayed initially. The actual string can be referred to by name.

*FvwmGtk: Button label cmd ...

Adds a button widget with the given label which will trigger the given commands when pressed. Commands can contain references to the values of widgets in the form $(name). These references are replaced by the actual values. The replacement is done recursively, ie the values can again contain references.

Commands can be strings to send to fvwm, system commands starting with and exclamation sign (which is stripped before execution) or the special command "close" to close the current dialog.

*FvwmGtk: CheckButton name label on-value off-value [ on ]

Adds a check button widget with the given label. The value referred to by name will be either on-value or off-value, depending on the state of the check button. The initial state is off, unless the optional argument is given.

*FvwmGtk: RadioGroup name

*FvwmGtk: EndRadioGroup

Start and end a composite widget which groups a number of mutually exclusive radio buttons. The value of the enables radio button can be referred to by name. Grouping radio buttons in this way doesn't influence their geometry. You can put a radio group in a row or column or even distribute it across several rows to determine the geometry.

*FvwmGtk: RadioButton label on-value [ on ]

Adds a radio button with the given label. Its initial state is off, unless the optional argument is given. There should probably be exactly one on radio button in a radio group. A radio button must be child of a radio group in order to be able to access its value.

*FvwmGtk: Notebook label

Opens a new notebook page with the given label. If there is already an open notebook, the page is appended to it. Otherwise a new notebook is created. A notebook page is a composite widget that expects one child.

*FvwmGtk: EndNotebook

Closes a notebook widget.

*FvwmGtk: Color name [ initial-value ]

Adds a color selector whose initial color is specified by initial-value and whose value can be referred to by name. The initial-value can be any color specification that is accepted by XParseColor. The returned color specifications are always of the form "rgb:rrrr/gggg/bbbb".

*FvwmGtk: Scale name [ vertical ] value lower

upper inc page-inc page-size [ digits ]" Adds a scale.

*FvwmGtk: SpinButton name value lower

upper inc page-inc page-size climb-rate [ digits ]" Adds a spin button.

*FvwmGtk: OptionMenu name

*FvwmGtk: EndOptionMenu

*FvwmGtk: Item label value [ on ]

Can be used to create option menus.

Common configuration

The following commands can be used for menus and dialogs.

*FvwmGtk: Separator

Appends a separator to the currently open menu, row or column.

*FvwmGtk: Destroy name

Destroys the specified menu or dialog.

*FvwmGtk: RCFile file

Note that this command should be issued before defining any menus or dialog. Hint for GNOME users: If you add instances of this command for the standard GNOME rc files, switching themes via the control-center will apply to FvwmGtk widgets as well, giving a very integrated appearance of the desktop.

*FvwmGtk: IconSize [ width height ]

If FvwmGtk has been compiled with imlib support, icons will be scaled to the size set by this command. Omitting the arguments disables scaling. Note that there is currently no way to change the amount of room left free for icons, thus using a width of more than 20 will not be very useful.

Commands

To invoke one of the previously defined menus or dialogs, use the fvwm command SendToModule.

SendToModule FvwmGtk name button

makes FvwmGtk pop up the menu or dialog named by the first argument. The second argument is the button that will be used for menu selection. For dialogs and menus which are not popped up from a button press, you can omit the button. Examples:

Mouse 3 R A SendToModule FvwmGtk Window-Ops 3
Key F10 R A SendToModule FvwmGtk Applications-Menu
Mouse 1 R A SendToModule FvwmGtk Quit-Verify-Dialog

Acknowledgments

The gtkpixmapmenuitem code and the code for underline accelerators is taken from libgnomeui.