Commit d26c1ce5 authored by Sven Neumann's avatar Sven Neumann Committed by Sven Neumann

libgimp/gimpui.c libgimp/gimpunit.c libgimpbase/gimpenv.c

2003-02-06  Sven Neumann  <sven@gimp.org>

	* libgimp/gimpui.c
	* libgimp/gimpunit.c
	* libgimpbase/gimpenv.c
	* libgimpmodule/gimpmodule.c
	* libgimpmodule/gimpmoduledb.c
	* libgimpwidgets/gimpchainbutton.c
	* libgimpwidgets/gimpdialog.c
	* libgimpwidgets/gimpfileselection.c
	* libgimpwidgets/gimphelpui.c
	* libgimpwidgets/gimpquerybox.c
	* libgimpwidgets/gimpsizeentry.c
	* libgimpwidgets/gimpunitmenu.c
	* libgimpwidgets/gimpwidgets.c: documentation fixes / improvements.
parent 799c3849
2003-02-06 Sven Neumann <sven@gimp.org>
* libgimp/gimpui.c
* libgimp/gimpunit.c
* libgimpbase/gimpenv.c
* libgimpmodule/gimpmodule.c
* libgimpmodule/gimpmoduledb.c
* libgimpwidgets/gimpchainbutton.c
* libgimpwidgets/gimpdialog.c
* libgimpwidgets/gimpfileselection.c
* libgimpwidgets/gimphelpui.c
* libgimpwidgets/gimpquerybox.c
* libgimpwidgets/gimpsizeentry.c
* libgimpwidgets/gimpunitmenu.c
* libgimpwidgets/gimpwidgets.c: documentation fixes / improvements.
2003-02-06 Sven Neumann <sven@gimp.org>
Switched to DocBook XML for the developers documentation:
......
......@@ -29,8 +29,8 @@
* @prog_name: The name of the plug-in which will be passed as argv[0] to
* gtk_init(). It's a convention to use the name of the
* executable and _not_ the PDB procedure name or something.
* @preview: #TRUE if the plug-in has some kind of preview in it's UI.
* Note that passing #TRUE is recommended also if one of the
* @preview: %TRUE if the plug-in has some kind of preview in it's UI.
* Note that passing %TRUE is recommended also if one of the
* used GIMP Library widgets contains a preview (like the image
* menu returned by gimp_image_menu_new()).
*
......
......@@ -140,7 +140,7 @@ gimp_unit_get_number_of_built_in_units (void)
* Returns the integer ID of the new #GimpUnit.
*
* Note that a new unit is always created with it's deletion flag
* set to #TRUE. You will have to set it to #FALSE with
* set to %TRUE. You will have to set it to %FALSE with
* gimp_unit_set_deletion_flag() to make the unit definition persistent.
*
* Returns: The ID of the new unit.
......@@ -186,7 +186,7 @@ gimp_unit_get_deletion_flag (GimpUnit unit)
* @deletion_flag: The new deletion_flag.
*
* Sets a #GimpUnit's @deletion_flag. If the @deletion_flag of a unit is
* #TRUE when GIMP exits, this unit will not be saved in the uses's
* %TRUE when GIMP exits, this unit will not be saved in the uses's
* "unitrc" file.
*
* Trying to change the @deletion_flag of a built-in unit will be silently
......
......@@ -140,7 +140,7 @@ gimp_unit_get_number_of_built_in_units (void)
* Returns the integer ID of the new #GimpUnit.
*
* Note that a new unit is always created with it's deletion flag
* set to #TRUE. You will have to set it to #FALSE with
* set to %TRUE. You will have to set it to %FALSE with
* gimp_unit_set_deletion_flag() to make the unit definition persistent.
*
* Returns: The ID of the new unit.
......@@ -186,7 +186,7 @@ gimp_unit_get_deletion_flag (GimpUnit unit)
* @deletion_flag: The new deletion_flag.
*
* Sets a #GimpUnit's @deletion_flag. If the @deletion_flag of a unit is
* #TRUE when GIMP exits, this unit will not be saved in the uses's
* %TRUE when GIMP exits, this unit will not be saved in the uses's
* "unitrc" file.
*
* Trying to change the @deletion_flag of a built-in unit will be silently
......
......@@ -431,7 +431,7 @@ gimp_path_runtime_fix (gchar **path)
* gimp_path_parse:
* @path: A list of directories separated by #G_SEARCHPATH_SEPARATOR.
* @max_paths: The maximum number of directories to return.
* @check: #TRUE if you want the directories to be checked.
* @check: %TRUE if you want the directories to be checked.
* @check_failed: Returns a #GList of path elements for which the
* check failed.
*
......
......@@ -236,8 +236,8 @@ gimp_module_unload (GTypeModule *module)
/**
* gimp_module_new:
* @filename: The filename of a loadable module.
* @load_inhibit: Pass #TRUE to exclude this module from auto-loading.
* @verbose: Pass #TRUE to enable debugging output.
* @load_inhibit: Pass %TRUE to exclude this module from auto-loading.
* @verbose: Pass %TRUE to enable debugging output.
*
* Creates a new #GimpModule instance.
*
......@@ -283,7 +283,7 @@ gimp_module_new (const gchar *filename,
* may implement. After successful query, the @info field of the
* #GimpModule struct will be available for further inspection.
*
* Return value: #TRUE on success.
* Return value: %TRUE on success.
**/
gboolean
gimp_module_query_module (GimpModule *module)
......@@ -371,7 +371,7 @@ gimp_module_modified (GimpModule *module)
/**
* gimp_module_set_load_inhibit:
* @module: A #GimpModule.
* @load_inhibit: Pass #TRUE to exclude this module from auto-loading.
* @load_inhibit: Pass %TRUE to exclude this module from auto-loading.
*
* Sets the @load_inhibit property if the module. Emits "modified".
**/
......
......@@ -188,7 +188,7 @@ gimp_module_db_finalize (GObject *object)
/**
* gimp_module_db_new:
* @verbose: Pass #TRUE to enable debugging output.
* @verbose: Pass %TRUE to enable debugging output.
*
* Creates a new #GimpModuleDB instance. The @verbose parameter will be
* passed to the created #GimpModule instances using gimp_module_new().
......
......@@ -193,11 +193,11 @@ gimp_chain_button_new (GimpChainPosition position)
/**
* gimp_chain_button_set_active:
* @button: Pointer to a #GimpChainButton.
* @button: Pointer to a #GimpChainButton.
* @active: The new state.
*
* Sets the state of the #GimpChainButton to be either locked (#TRUE) or
* unlocked (#FALSE) and changes the showed pixmap to reflect the new state.
* Sets the state of the #GimpChainButton to be either locked (%TRUE) or
* unlocked (%FALSE) and changes the showed pixmap to reflect the new state.
*/
void
gimp_chain_button_set_active (GimpChainButton *button,
......@@ -207,12 +207,15 @@ gimp_chain_button_set_active (GimpChainButton *button,
if (button->active != active)
{
guint num;
button->active = active ? TRUE : FALSE;
gtk_image_set_from_stock
(GTK_IMAGE (button->image),
gimp_chain_stock_items[((button->position & GIMP_CHAIN_LEFT) << 1) + ! button->active],
GTK_ICON_SIZE_BUTTON);
num = ((button->position & GIMP_CHAIN_LEFT) << 1) + (active ? 0 : 1);
gtk_image_set_from_stock (GTK_IMAGE (button->image),
gimp_chain_stock_items[num],
GTK_ICON_SIZE_BUTTON);
}
}
......@@ -222,7 +225,7 @@ gimp_chain_button_set_active (GimpChainButton *button,
*
* Checks the state of the #GimpChainButton.
*
* Returns: TRUE if the #GimpChainButton is active (locked).
* Returns: %TRUE if the #GimpChainButton is active (locked).
*/
gboolean
gimp_chain_button_get_active (GimpChainButton *button)
......
......@@ -117,7 +117,7 @@ gimp_dialog_delete_event (GtkWidget *widget,
* @allow_grow: ... it't @allow_grow flag and ...
* @auto_shrink: ... it's @auto_shrink flag which will all be set with
* gtk_window_set_policy().
* @...: A #NULL terminated @va_list destribing the
* @...: A %NULL-terminated @va_list destribing the
* action_area buttons.
*
* This function simply packs the action_area arguments passed in "..."
......@@ -238,7 +238,7 @@ gimp_dialog_newv (const gchar *title,
/**
* gimp_dialog_create_action_area:
* @dialog: The #GimpDialog you want to create the action_area for.
* @...: A #NULL terminated @va_list destribing the action_area buttons.
* @...: A %NULL-terminated @va_list destribing the action_area buttons.
*
* This function simply packs the action_area arguments passed in "..."
* into a @va_list variable and passes everything to
......
......@@ -188,8 +188,8 @@ gimp_file_selection_destroy (GtkObject *object)
* gimp_file_selection_new:
* @title: The title of the #GtkFileSelection dialog.
* @filename: The initial filename.
* @dir_only: #TRUE if the file selection should accept directories only.
* @check_valid: #TRUE if the widget should check if the entered file
* @dir_only: %TRUE if the file selection should accept directories only.
* @check_valid: %TRUE if the widget should check if the entered file
* really exists.
*
* Creates a new #GimpFileSelection widget.
......@@ -245,7 +245,7 @@ gimp_file_selection_get_filename (GimpFileSelection *selection)
* @selection: The file selection you want to set the filename for.
* @filename: The new filename.
*
* If you specified @check_valid as #TRUE in gimp_file_selection_new()
* If you specified @check_valid as %TRUE in gimp_file_selection_new()
* the #GimpFileSelection will immediately check the validity of the file
* name.
*
......
......@@ -188,8 +188,8 @@ gimp_file_selection_destroy (GtkObject *object)
* gimp_file_selection_new:
* @title: The title of the #GtkFileSelection dialog.
* @filename: The initial filename.
* @dir_only: #TRUE if the file selection should accept directories only.
* @check_valid: #TRUE if the widget should check if the entered file
* @dir_only: %TRUE if the file selection should accept directories only.
* @check_valid: %TRUE if the widget should check if the entered file
* really exists.
*
* Creates a new #GimpFileSelection widget.
......@@ -245,7 +245,7 @@ gimp_file_selection_get_filename (GimpFileSelection *selection)
* @selection: The file selection you want to set the filename for.
* @filename: The new filename.
*
* If you specified @check_valid as #TRUE in gimp_file_selection_new()
* If you specified @check_valid as %TRUE in gimp_file_selection_new()
* the #GimpFileSelection will immediately check the validity of the file
* name.
*
......
......@@ -181,14 +181,14 @@ gimp_help_connect (GtkWidget *widget,
/**
* gimp_help_set_help_data:
* @widget: The #GtkWidget you want to set a @tooltip and/or @help_data for.
* @tooltip: The text for this widget's tooltip.
* @tooltip: The text for this widget's tooltip (or %NULL).
* @help_data: The @help_data for the #GtkTipsQuery tooltips inspector.
*
* The reason why we don't use gtk_tooltips_set_tip() is that it's
* impossible to set a @private_tip (aka @help_data) without a visible
* @tooltip.
*
* This function can be called with @tooltip == #NULL. Use this feature
* This function can be called with %NULL for @tooltip. Use this feature
* if you want to set a HTML help link for a widget which shouldn't have
* a visible tooltip.
*
......
......@@ -387,7 +387,7 @@ gimp_query_double_box (const gchar *title,
* @unit: The unit initially shown by the #GimpUnitMenu.
* @resolution: The resolution (in dpi) which will be used for pixel/unit
* calculations.
* @dot_for_dot: #TRUE if the #GimpUnitMenu's initial unit should be "pixels".
* @dot_for_dot: %TRUE if the #GimpUnitMenu's initial unit should be "pixels".
* @object: The object this query box is associated with.
* @signal: The object's signal which will cause the query box
* to be closed.
......
......@@ -203,17 +203,18 @@ gimp_size_entry_finalize (GObject *object)
* gimp_size_entry_new:
* @number_of_fields: The number of input fields.
* @unit: The initial unit.
* @unit_format: A printf-like unit-format string (see #GimpUnitMenu).
* @menu_show_pixels: #TRUE if the unit menu shold contain an item for
* @unit_format: A printf-like unit-format string as is used with
* gimp_unit_menu_new().
* @menu_show_pixels: %TRUE if the unit menu shold contain an item for
* GIMP_UNIT_PIXEL (ignored if the @update_policy is not
* GIMP_SIZE_ENTRY_UPDATE_NONE).
* @menu_show_percent: #TRUE if the unit menu shold contain an item for
* @menu_show_percent: %TRUE if the unit menu shold contain an item for
* GIMP_UNIT_PERCENT.
* @show_refval: #TRUE if you want an extra "refenence value"
* @show_refval: %TRUE if you want an extra "refenence value"
* spinbutton per input field.
* @spinbutton_width: The minimal horizontal size of the #GtkSpinButton's.
* @update_policy: How the automatic pixel <-> real-world-unit calculations
* should be performed.
* @update_policy: How the automatic pixel <-> real-world-unit
* calculations should be done.
*
* Creates a new #GimpSizeEntry widget.
*
......@@ -239,7 +240,8 @@ gimp_size_entry_finalize (GObject *object)
*
* The #GimpSizeEntry is derived from #GtkTable and will have
* an empty border of one cell width on each side plus an empty column left
* of the #GimpUnitMenu to allow the caller to add labels or a #GimpChainButton.
* of the #GimpUnitMenu to allow the caller to add labels or a
* #GimpChainButton.
*
* Returns: A Pointer to the new #GimpSizeEntry widget.
**/
......@@ -360,7 +362,8 @@ gimp_size_entry_new (gint number_of_fields,
gtk_widget_show (gsef->refval_spinbutton);
}
if (gse->menu_show_pixels && !gse->show_refval && (unit == GIMP_UNIT_PIXEL))
if (gse->menu_show_pixels && (unit == GIMP_UNIT_PIXEL) &&
! gse->show_refval)
gtk_spin_button_set_digits (GTK_SPIN_BUTTON (gsef->value_spinbutton),
gsef->refval_digits);
}
......@@ -383,15 +386,15 @@ gimp_size_entry_new (gint number_of_fields,
/**
* gimp_size_entry_add_field:
* @gse: The sizeentry you want to add a field to.
* @value_spinbutton: The spinbutton to display the field's value.
* @gse: The sizeentry you want to add a field to.
* @value_spinbutton: The spinbutton to display the field's value.
* @refval_spinbutton: The spinbutton to display the field's reference value.
*
* Adds an input field to the #GimpSizeEntry.
*
* The new input field will have the index 0. If you specified @show_refval
* as #TRUE in gimp_size_entry_new() you have to pass an additional
* #GtkSpinButton to hold the reference value. If @show_refval was #FALSE,
* as %TRUE in gimp_size_entry_new() you have to pass an additional
* #GtkSpinButton to hold the reference value. If @show_refval was %FALSE,
* @refval_spinbutton will be ignored.
**/
void
......@@ -514,8 +517,8 @@ gimp_size_entry_attach_label (GimpSizeEntry *gse,
* @gse: The sizeentry you want to set a resolution for.
* @field: The index of the field you want to set the resolution for.
* @resolution: The new resolution (in dpi) for the chosen @field.
* @keep_size: #TRUE if the @field's size in pixels should stay the same.
* #FALSE if the @field's size in units should stay the same.
* @keep_size: %TRUE if the @field's size in pixels should stay the same.
* %FALSE if the @field's size in units should stay the same.
*
* Sets the resolution (in dpi) for field # @field of the #GimpSizeEntry.
*
......@@ -563,7 +566,7 @@ gimp_size_entry_set_resolution (GimpSizeEntry *gse,
* Sets the pixel values for field # @field of the #GimpSizeEntry
* which will be treated as 0% and 100%.
*
* These values will be used if you specified @menu_show_percent as #TRUE
* These values will be used if you specified @menu_show_percent as %TRUE
* in gimp_size_entry_new() and the user has selected GIMP_UNIT_PERCENT in
* the #GimpSizeEntry's #GimpUnitMenu.
*
......
......@@ -151,11 +151,11 @@ gimp_unit_menu_finalize (GObject *object)
* @format: A printf-like format string which is used to create the unit
* strings.
* @unit: The initially selected unit.
* @show_pixels: #TRUE if the unit menu should contain an item for
* @show_pixels: %TRUE if the unit menu should contain an item for
* GIMP_UNIT_PIXEL.
* @show_percent: #TRUE in the unit menu should contain an item for
* @show_percent: %TRUE in the unit menu should contain an item for
* GIMP_UNIT_PERCENT.
* @show_custom: #TRUE if the unit menu should contain a "More..." item for
* @show_custom: %TRUE if the unit menu should contain a "More..." item for
* opening the user-defined-unit selection dialog.
*
* Creates a new #GimpUnitMenu widget.
......@@ -243,7 +243,8 @@ gimp_unit_menu_new (const gchar *format,
gtk_widget_show (menuitem);
menuitem =
gtk_menu_item_new_with_label (gimp_unit_menu_build_string (format, unit));
gtk_menu_item_new_with_label (gimp_unit_menu_build_string (format,
unit));
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menuitem);
g_object_set_data (G_OBJECT (menuitem), "gimp_unit_menu",
GINT_TO_POINTER (unit));
......
......@@ -82,8 +82,8 @@ gimp_widgets_init (void)
/**
* gimp_option_menu_new:
* @menu_only: #TRUE if the function should return a #GtkMenu only.
* @...: A #NULL terminated @va_list describing the menu items.
* @menu_only: %TRUE if the function should return a #GtkMenu only.
* @...: A %NULL-terminated @va_list describing the menu items.
*
* Convenience function to create a #GtkOptionMenu or a #GtkMenu.
*
......@@ -191,13 +191,13 @@ gimp_option_menu_new (gboolean menu_only,
/**
* gimp_option_menu_new2:
* @menu_only: #TRUE if the function should return a #GtkMenu only.
* @menu_only: %TRUE if the function should return a #GtkMenu only.
* @menu_item_callback: The callback each menu item's "activate" signal will
* be connected with.
* @menu_item_callback_data:
* The data which will be passed to g_signal_connect().
* @initial: The @item_data of the initially selected menu item.
* @...: A #NULL terminated @va_list describing the menu items.
* @...: A %NULL-terminated @va_list describing the menu items.
*
* Convenience function to create a #GtkOptionMenu or a #GtkMenu.
*
......@@ -380,9 +380,9 @@ gimp_option_menu_set_sensitive (GtkOptionMenu *option_menu,
/**
* gimp_radio_group_new:
* @in_frame: #TRUE if you want a #GtkFrame around the radio button group.
* @frame_title: The title of the Frame or #NULL if you don't want a title.
* @...: A #NULL terminated @va_list describing the radio buttons.
* @in_frame: %TRUE if you want a #GtkFrame around the radio button group.
* @frame_title: The title of the Frame or %NULL if you don't want a title.
* @...: A %NULL-terminated @va_list describing the radio buttons.
*
* Convenience function to create a group of radio buttons embedded into
* a #GtkFrame or #GtkVbox.
......@@ -483,16 +483,16 @@ gimp_radio_group_new (gboolean in_frame,
/**
* gimp_radio_group_new2:
* @in_frame: #TRUE if you want a #GtkFrame around the
* @in_frame: %TRUE if you want a #GtkFrame around the
* radio button group.
* @frame_title: The title of the Frame or #NULL if you don't want
* @frame_title: The title of the Frame or %NULL if you don't want
* a title.
* @radio_button_callback: The callback each button's "toggled" signal will
* be connected with.
* @radio_button_callback_data:
* The data which will be passed to g_signal_connect().
* @initial: The @item_data of the initially pressed radio button.
* @...: A #NULL terminated @va_list describing
* @...: A %NULL-terminated @va_list describing
* the radio buttons.
*
* Convenience function to create a group of radio buttons embedded into
......@@ -811,12 +811,12 @@ gimp_scale_entry_new_internal (gboolean color_scale,
* @step_increment: The step increment.
* @page_increment: The page increment.
* @digits: The number of decimal digits.
* @constrain: #TRUE if the range of possible values of the
* @constrain: %TRUE if the range of possible values of the
* #GtkSpinButton should be the same as of the #GtkHScale.
* @unconstrained_lower: The spinbutton's lower boundary
* if @constrain == #FALSE.
* if @constrain == %FALSE.
* @unconstrained_upper: The spinbutton's upper boundary
* if @constrain == #FALSE.
* if @constrain == %FALSE.
* @tooltip: A tooltip message for the scale and the spinbutton.
* @help_data: The widgets' help_data (see gimp_help_set_help_data()).
*
......@@ -1078,19 +1078,19 @@ gimp_coordinates_callback (GtkWidget *widget,
/**
* gimp_coordinates_new:
* @unit: The initial unit of the #GimpUnitMenu.
* @unit_format: The unit format string as passed to
* gimp_size_entry_new().
* @menu_show_pixels: #TRUE if the #GimpUnitMenu should contain an item for
* GIMP_UNIT_PIXEL.
* @menu_show_percent: #TRUE if the #GimpUnitMenu should contain an item for
* GIMP_UNIT_PERCENT.
* @unit_format: A printf-like unit-format string as is used with
* gimp_unit_menu_new().
* @menu_show_pixels: %TRUE if the #GimpUnitMenu should contain an item
* for GIMP_UNIT_PIXEL.
* @menu_show_percent: %TRUE if the #GimpUnitMenu should contain an item
* for GIMP_UNIT_PERCENT.
* @spinbutton_width: The horizontal size of the #GimpSizeEntry's
* #GtkSpinButton's.
* @update_policy: The update policy for the #GimpSizeEntry.
* @chainbutton_active: #TRUE if the attached #GimpChainButton should be
* @chainbutton_active: %TRUE if the attached #GimpChainButton should be
* active.
* @chain_constrains_ratio: #TRUE if the chainbutton should constrain the
* fields' aspect ratio. If #FALSE, the values will
* @chain_constrains_ratio: %TRUE if the chainbutton should constrain the
* fields' aspect ratio. If %FALSE, the values will
* be constrained.
* @xlabel: The label for the X coordinate.
* @x: The initial value of the X coordinate.
......@@ -1228,8 +1228,8 @@ gimp_coordinates_new (GimpUnit unit,
* @xpm_data: The XPM data which will be passed to gimp_pixmap_new().
* @text: An optional text which will appear right of the pixmap.
*
* Convenience function that creates a #GtkButton with a #GimpPixmap and an
* optional #GtkLabel.
* Convenience function that creates a #GtkButton with a #GimpPixmap
* and an optional #GtkLabel.
*
* Returns: The new #GtkButton.
**/
......@@ -1351,7 +1351,7 @@ gimp_toggle_button_update (GtkWidget *widget,
* gimp_radio_button_update:
* @widget: A #GtkRadioButton.
* @data: A pointer to a #gint variable which will store the value of
* GPOINTER_TO_INT (g_object_get_user_data(@widget, "gimp-item-data")).
* GPOINTER_TO_INT (g_object_get_data (@widget, "gimp-item-data")).
*
* Note that this function calls gimp_toggle_button_sensitive_update().
**/
......@@ -1376,7 +1376,7 @@ gimp_radio_button_update (GtkWidget *widget,
* gimp_menu_item_update:
* @widget: A #GtkMenuItem.
* @data: A pointer to a #gint variable which will store the value of
* GPOINTER_TO_INT (g_object_get_data(@widget, "gimp-item-data")).
* GPOINTER_TO_INT (g_object_get_data (@widget, "gimp-item-data")).
**/
void
gimp_menu_item_update (GtkWidget *widget,
......@@ -1507,16 +1507,16 @@ gimp_unit_menu_update (GtkWidget *widget,
* @table: The #GtkTable the widgets will be attached to.
* @column: The column to start with.
* @row: The row to attach the widgets.
* @label_text: The text for the #GtkLabel which will be attached left of the
* widget.
* @label_text: The text for the #GtkLabel which will be attached left of
* the widget.
* @xalign: The horizontal alignment of the #GtkLabel.
* @yalign: The vertival alignment of the #GtkLabel.
* @widget: The #GtkWidget to attach right of the label.
* @colspan: The number of columns the widget will use.
* @left_align: #TRUE if the widget should be left-aligned.
* @left_align: %TRUE if the widget should be left-aligned.
*
* Note that the @label_text can be #NULL and that the widget will be attached
* starting at (@column + 1) in this case, too.
* Note that the @label_text can be %NULL and that the widget will be
* attached starting at (@column + 1) in this case, too.
*
* Returns: The created #GtkLabel.
**/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment