Restructure how we look for Read files slightly.

[fvwm.git] / modules / FvwmGtk / FvwmGtk.1.in

.\" @(#)@PACKAGE@-@VERSION@ @RELDATELONG@
.de EX          \"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +.5i
..
.de EE
.fi
.in -.5i
.if n .sp 1
.if t .sp .5
..
.TH FvwmGtk 1 "@RELDATELONG@ (@VERSION@)" Fvwm "Fvwm Modules"
.UC
.SH NAME
\fBFvwmGtk\fP \- the fvwm GTK module
.SH SYNOPSIS
\fBFvwmGtk\fP is spawned by fvwm, so no command line invocation will work.
From within the fvwm's configuration file, \fBFvwmGtk\fP is spawned as follows:
.EX
Module FvwmGtk [ name ]
.EE
or from within an fvwm pop-up menu:
.EX
DestroyMenu Module-Popup
AddToMenu   Module-Popup "Modules" Title
AddToMenu   Module-Popup "Gtk" Module FvwmGtk [ name ]
.EE

.SH DESCRIPTION
The \fBFvwmGtk\fP module implements GTK-based alternatives to the
GUI elements in fvwm, namely the builtin menus and the FvwmForm dialogs.

.SH INVOCATION
No command line invocation is possible.
\fBFvwmGtk\fP must be invoked by the
\fBfvwm\fP window manager.
When invoked with the optional \fIname\fP argument, \fIname\fP
is used to find configuration commands and configuration files
instead of "FvwmGtk".

.SH CONFIGURATION OPTIONS
\fBFvwmGtk\fP 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.

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

If the optional \fIname\fP is used to start FvwmGtk, \fIname\fP 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.
.EX
        SendToModule FvwmGtk menu-example 1
        SendToModule FvwmGtk dialog-example
.EE

.SH 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.

.IP "*FvwmGtk: Menu \fBname\fP"
Instructs \fBFvwmGtk\fP 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.

.IP "*FvwmGtk: Title \fBlabel\fP [ \fBicon\fP [ \fBr_label\fP ] ]"
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.

.IP "*FvwmGtk: Item \fBlabel\fP \fBaction\fP [ \fBicon\fP [ \fBr_label\fP ] ]"
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.

.IP "*FvwmGtk: Submenu \fBlabel\fP \fBname\fP [ \fBicon\fP ]"
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.

.IP "*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.

.SH 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.

.IP "*FvwmGtk: WindowList \fBname\fP [ \fBoption\fP... ]"
Creates a window-list bound to \fBname\fP. 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.


.SH 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: \fIWidget\fP \fIwidget-specific args\fP [ -- \fIgeneral-args\fP ]

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

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

\fIdefault\fP means that the widget is the initial default widget.

\fIfocus\fP means that the widget initially has the keyboard focus.

\fIexpand\fP, \fIfill\fP, \fIpadding\fP 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.

.IP "*FvwmGtk: Dialog \fBname\fP \fBtitle\fP [ \fBcenter\fP ]"
Starts or reopens a dialog named by the first argument. \fBtitle\fP
is used as the window title. If the optional argument \fBcenter\fP 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.

.IP "*FvwmGtk: Box [ \fBvertical\fP ] [ \fBhomogeneous\fP ] [ \fBspacing\fP [ \fBborder\fP ] ]"
.IP "*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).

.IP "*FvwmGtk: Frame \fBlabel\fP [ \fBborder\fP ]"
.IP "*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.

.IP "*FvwmGtk: Label \fBlabel\fP"
Adds a label widget.

.IP "*FvwmGtk: Entry \fBname\fP [ \fBinitial-value\fP ]"
Adds a widget which allows the user to enter a string. If given, the
\fBinitial-value\fP is displayed initially. The actual string can
be referred to by \fBname\fP.

.IP "*FvwmGtk: Button \fBlabel\fP \fBcmd\fP ..."
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.

.IP "*FvwmGtk: CheckButton \fBname\fP \fBlabel\fP \fBon-value\fP \fBoff-value\fP [ \fBon\fP ]"
Adds a check button widget with the given label. The value referred to
by \fBname\fP will be either \fBon-value\fP or \fBoff-value\fP, depending
on the state of the check button. The initial state is off, unless
the optional argument is given.

.IP "*FvwmGtk: RadioGroup \fBname\fP"
.IP "*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 \fBname\fP. 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.

.IP "*FvwmGtk: RadioButton \fBlabel\fP \fBon-value\fP [ \fBon\fP ]"
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 \fBon\fP
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.

.IP "*FvwmGtk: Notebook \fBlabel\fP"
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.

.IP "*FvwmGtk: EndNotebook"
Closes a notebook widget.

.IP "*FvwmGtk: Color \fBname\fP [ \fBinitial-value\fP ]"
Adds a color selector whose initial color is specified by \fBinitial-value\fP
and whose value can be referred to by \fBname\fP. The \fBinitial-value\fP
can be any color specification that is accepted by XParseColor. The returned
color specifications are always of the form "rgb:rrrr/gggg/bbbb".

.IP "*FvwmGtk: Scale \fBname\fP [ \fBvertical\fP ] \fBvalue\fP \fBlower\fP
\fBupper\fP \fBinc\fP \fBpage-inc\fP \fBpage-size\fP [ \fBdigits\fP ]"
Adds a scale.

.IP "*FvwmGtk: SpinButton \fBname\fP \fBvalue\fP \fBlower\fP
\fBupper\fP \fBinc\fP \fBpage-inc\fP \fBpage-size\fP \fBclimb-rate\fP [
\fBdigits\fP ]"
Adds a spin button.

.IP "*FvwmGtk: OptionMenu \fBname\fP"
.IP "*FvwmGtk: EndOptionMenu"
.IP "*FvwmGtk: Item \fBlabel\fP \fBvalue\fP [ \fBon\fP ]"
Can be used to create option menus.


.SH COMMON CONFIGURATION
The following commands can be used for menus and dialogs.

.IP "*FvwmGtk: Separator"
Appends a separator to the currently open menu, row or column.

.IP "*FvwmGtk: Destroy \fBname\fP"
Destroys the specified menu or dialog.

.IP "*FvwmGtk: RCFile \fBfile\fP"
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.

.IP "*FvwmGtk: IconSize [ \fBwidth\fP \fBheight\fP ]"
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.

.SH COMMANDS
To invoke one of the previously defined menus or dialogs, use the fvwm
command \fISendToModule\fP.

.IP "SendToModule FvwmGtk \fBname\fP \fBbutton\fP"
makes \fBFvwmGtk\fP 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:
.EX
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
.EE

.SH AUTHOR
\fIMatthias Clasen\fP <clasen@mathematik.uni-freiburg.de>

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

.SH BUGS
The builtin menus offer many features which the GTK menus currently
don't have. None of the features of the builtin window-list have
been implemented.