Writing source code for Amaya

This document is intended to help writing source code in Amaya. It concerns file names, variables, function signatures, etc.

Files location

The root directory is called Amaya and includes 11 sub-directories. The libwww is stored in a separated hierarchy and its root directory libwww must be a sibling of the Amaya root directory.

• the directory amaya includes source files of the Amaya application: c code (.c), common structures and variables ( h). A sub-directory f includes function signatures (_f.h files are automatically generated by "make proto" on Unix platforms).
• the directory batch includes the source of Thot compilers.
• the directories libjpeg, libpng, pluginlib, tablelib include the source code of related libraries.
• as the thotlib is a large piece of code the source code is ranged into several sub-directories.
  • the sub-directory base collects basic modules (memory allocation, registry, file access).
  • the sub-directory content collects text management modules.
  • the sub-directory dialogue collects all UI modules.
  • the sub-directory document collects modules which manage Thot documents.
  • the sub-directory editing collects editing modules.
  • the sub-directory image collects image drivers.
  • the sub-directory include collects external Thotlib declarations.
  • the sub-directory internals collects internal Thotlib declarations. There are 3 different sub-directory:
    • h: for global structure types and constants,
    • var: for global variables. Files are noted _tv.h and their inclusion should be preceded by a definition of THOT_EXPORT

      #DEFINE THOT_EXPORT

      or

      #DEFINE THOT_EXPORT extern

    • f: for function declarations. Files are noted _f.h.
  • the sub-directory presentation collects modules which manage document styles.
  • the sub-directory tree collects modules which manipulate document tree structures (Abstract Trees) and attribute.
  • the sub-directory view collects modules which manage document view (Abstract Boxes and Boxes).
• the directory tools includes the source code of building applications which allows us to generate file dependencies ("make dep") or or to generate function prototypes( "make proto").

Types declaration

To avoid conflicts with included libraries and to share the code as often as possible, the Thot library defines its own types for booleans, widgets, buttons, pixmaps and windows. All these declarations are located in files Amaya/thotlib/include/thot_sys.h, Amaya/thotlib/include/thot_gui.h and Amaya/thotlib/include/thot_uio.h. See also Unicode conventions.

We recommand to organize modules in five clearly separated sections:

1. A global comment which gives the COPYRIGHT, the role of the module and the list of its authors.
2. A section that declares all types used in the module. It is often a list of includes.
3. A section that declares the variables used in the module. It is a list of includes preceded by the definition of the macro THOT_EXPORT. Static variables of the module must be declared in this section too.
4. A section that declares external functions used in the module. It is a list of includes.
5. The core section of the module.

Notations

That concerns local variables, global variables, function headings and function names.

• Local variables:

  Local variables and function parameters must start with a lowercase character.

• Global variables:

  Global variables must start with a uppercase character. When they are global but only used into one module. They must be declared static in that module. When they are used in more than one module they must be declared in a included file:

  • in the Thotlib code, they are declared into one of the files
    Amaya/thotlib/internals/var/*tv.h
  • in the Amaya code, they are stored in include file Amaya/amaya/*h
• Function headings:

  All functions should include a comment at the top which explains what the function does, what is the signification of parameters, what is the output.

  A function must be declared static if it is only used into the current module.

  Function declarations must be done according to the standard C convention.

  By example:

  /*----------------------------------------------------------------------
    GetStyleContents returns a buffer that contains the whole text of the
    style element el. It returns NULL if the element is empty.
    The buffer should be freed by the caller.
    ----------------------------------------------------------------------*/
  STRING              GetStyleContents (Element el)
  {
  ...
  }
   

• Function names:

  A function name must start with a uppercase character and more if it includes different words.

  There are specific conventions for functions which are exported by the Thotlib.

  TtaXXX

  is the name of an API function. It should be documented in APIman.html.

  TtcXXX

  is the name of a Thot standard command. It has 2 parameters: the document and the view even if one of these parameters is not used by the function. That function can be used by the application interface (see the file Amaya/amaya/EDITOR.A) like the command CloseView which uses TtcCloseView.

  TteXXX

  is the name of a Thotlib function which manages Thot events. That function cannot be used freely.

Adding a new dialogue

Adding a new dialogue entry in any Amaya menu is by by several steps:

1. Editing the file Amaya/amaya/EDITOR.A

   By example, adding the following line "view:1 Style button:BValidCSS -> ValidCSS;" will create a new entry "BValidCSS" into the "Style" menu, only displayed by the formatted view of the document (view:1). When selecting that menu entry Amaya will call the function "ValidCSS (document, view)".

2. Writing the called function with the right signature: (the Document parameter and the View parameter).

   After compiling Amaya, the building will stop because the new function is not defined, but in the file Amaya/obj/amaya/EDITORactions.proto you will find the declaration of the function (ValidCSS () in our example). Take a copy of that declaration and put it into the file Amaya/amaya/EDITORactions.c. Then you have to write the code of the function.

3. Adding the text of the new entry into dialogue files.

   For that, check the position of the new dialogue in the generated file Amaya/obj/amaya/EDITOR.h

   Open the XML base of dialogues: Amaya/tools/xmldialogues/bases/base_am_dia.xml

   It's available on the CVS base but not included in the tar source (please ask us if you need it).

   Add the corresponding entry at the right place in the base, but pay attention that this XML base uses UTF-8 characters.

   Dialogue files will be then generated by the PERL script Amaya/tools/xmldialogues/scripts/Am_dial_managment.pl

4. Updating the file of Amaya profiles Amaya/config/ProfileDefs to make that function available in right profiles.
5. Updating the section Keyboard Shortcuts in the file Amaya/doc/amaya/Configure.html if that function should be acceded by a shortcut.

Adding a new Help menu entry

Help menu entries are handled as dialogue entries. Therefore, you'll have to add a new dialogue entry, a callback procedure, connect this procedure to the dialogue entry, and make this procedure open the related manual page

Follow the instructions for adding a new dialogue entry, inspiring yourself from the existing help menu entries. For example, the Help/Configure entry is defined as follows in the EDITOR.A file:

      view:1 Help_ button:BHelpConfigure -> HelpConfigure;

The callback procedure and the definition of the manual pages are done in the init.c file. To associate a manual page to the procedure, you first need to declare it in the helpmenu.h file. In this find, you'll find an array called Manual and some macro definitions to associate a names with the Manual entries. For HelpConfigure, the macro is called CONFIGURE.

Once you've done this, open the init file, search for the Help* procedures and add your new procedure. For example, HelpConfigure is specified as follows:

/*----------------------------------------------------------------------
  -----------------------------------------------------------------------*/
void HelpConfigure (Document document, View view)
{
   DisplayHelp (document, CONFIGURE);
}

The DisplayHelp function will open a new document window and show the document specified in the Manual index (file helpmenu.h). Note that we use the macro rather than the index number to refer to the index entry.

Copyright  ©  1994-2003 INRIA and W3C^® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply. Your interactions with this site are in accordance with our public and Member privacy statements.