Writing Extended Tips

    From The Document Foundation Wiki


    Writing Extended Tips in LibreOffice Dialogs

    This page describes the process to write extended tips to LibreOffice ui dialogs.

    Introduction

    Extended Tips provide a brief description about buttons and commands. To display an extended tip, press Shift+F1, then point to a button or command.

    Note pin.svg

    Note:
    If you always want extended tips instead of tips, enable the extended tips on Tools ▸ Options ▸ LibreOffice ▸ General.

    Extended tips contents were originally written in Help pages (xhp) inside <ahelp> tags. Often the extended tip is used in both dialogs and in the Help page. When the extend tip is not to be displayed in the help page, an attribute visibility="hidden" is added to the tag.

    In other words, extended tips with hidden flags are not displayed in the Help page, and there is no need to update them. However, their contents may be important and they were kept as is, until migrated to the respective UI dialog.

    Most extended tips were automatically migrated from XHP files to the proper ui dialogs. Some extended tips were not because they were too hard to handle in an automation script. These extended tips were left for manual handling.

    Extended tip in LibreOffice Dialogs

    A LibreOffice dialog can have as many extended tip as widgets inside it. Not every widget deserves an extended tip and some widget are rather self explanatory and the extended tip simply does not add relevant information (e.g no need to a tip for OK or Cancel buttons).

    UI dialogs widgets that deserves an extended tips are (not an extensive list):

    • Text input box
    • Text area box
    • Drop down lists
    • Buttons with specific actions
    • Check box
    • Radio button
    • Spin box
    • Other.

    Adding Extended Tip in LibreOffice Dialogs

    LibreOffice UI dialogs are handled with the Glade tool. You must be minimally familiar with Glade to be able to edit a dialog file.

    Nevertheless adding extended tip to a dialog is an easy task.

    1. Open the dialog file in Glade
    2. Locate and highlight (select) the widget to get the extended tip
    3. Click on the accessibility tab of the widget located in the right side of the Glade window
    4. Click on the Down arrow (pen icon) of the Accessibility Description input box
    5. Fill the dialog with the following information
      1. Mark the Translatable checkbox ALWAYS
      2. In the Text: box, write the extended tip contents.
      3. In the Context for translator input box, add [dialog_file]|extended_tip|[widget_name], where
        [dialog_file]
        the dialog file name with no .ui extension
        "extended_tip"
        textual.
        [widget_name]
        the name of the widget in the dialog
      Example: for the ctlFavoriteswin widget of the svx/uiconfig/ui/fontworkgallerydialog.ui dialog, enter fontworkgallerydialog|extended_tip|ctlFavoriteswin
    6. Repeat for other widgets extended tips
    7. Save the file when done
    8. Build the software and check the extended tip.

    Adding Extended Tip from the Help files

    As said above, the <ahelp> tag was designed to hold extended tips in older versions of LibreOffice. Some <ahelp> contents were not yet migrated and must be done manually.

    Fill the Text: box above with the text copied from the proper <ahelp> contents.

    • You must locate and copy the right content from the correct file.
    • Remove all and every xml tag from the text. Extended tips were set to not have markup. In other words, remove <emph>, <switchinline>, <item>, etc... from the text. Rewrite or adjust the text if necessary.

    Example

    Example of an extended tip migration to dialog file
    <ahelp> text Extended tip dialog

    <ahelp hid="." visibility="hidden">Select a Fontwork style and click <emph>OK</emph> to insert the Fontwork into your document. Double-click or <switchinline select="sys"><caseinline select="MAC"><keycode>Command</keycode></caseinline><defaultinline><keycode>Ctrl</keycode></defaultinline></switchinline>+double-click the Fontwork in your document to enter text edit mode and change the text.</ahelp>

    Select a Fontwork style and click OK to insert the Fontwork into your document. Double-click or Ctrl (Command) + double-click the Fontwork in your document to enter text edit mode and change the text.
    [dialog_file]
    the dialog file name with no .ui extension
    "extended_tip"
    textual.
    [widget_name]
    the name of the widget in the dialog
    fontworkgallerydialog|extented_tip|ctlFavoriteWin

    Glade main screen

    Extended tip input dialog in Glade