client_c.h

The major functionality added in this release includes: - Rootless mode in X11 - Widget Templt

/* $Id: client_c.h,v 1.92 2002/09/25 04:07:44 micahjd Exp $
 *
 * picogui/client_c.h - The PicoGUI API provided by the C client lib
 *
 * PicoGUI small and efficient client/server GUI
 * Copyright (C) 2000-2002 Micah Dowty <[e-mail]>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 * 
 * Contributors: 
 * 
 *  Philippe Ney <[e-mail]>
 * 
 * 
 */

#ifndef _H_PG_CLI_C
#define _H_PG_CLI_C

#include <stdio.h>   /* For NULL and FILE */
#ifdef __NetBSD__  
#include <sys/types.h>
#include <sys/time.h>
#include <unistd.h>
#endif

#ifdef __linux__
#include <sys/types.h>
#include <sys/time.h>
#include <unistd.h>
#endif

/*! 
 * \file client_c.h
 * \brief C Client API Header
 * 
 * client_c.h contains declarations for all core PicoGUI API functions
 * and structures. This does not include the PGFX graphics module, or the
 * low-level canvas commands. All constants common to client and server are
 * in constants.h, and the network interface between client and server is
 * defined in network.h. Usually this file does not need to be included
 * separately, it is included with <tt>\#include <picogui.h></tt>
 */

/*!
 * \defgroup pgapi Core PicoGUI API
 *
 * These are the basic PicoGUI APIs used for connecting to the server
 * and manipulating data within it. This does not include the PGFX and
 * Standard Dialog modules.
 *
 * \{
 */

/******************** Client-specific constants and data types */

/*!
 * \defgroup constdata Constants and Data Types
 *
 * pgEvent and other data structures and constants specific to the client.
 * These values are interpreted in the client library, not the server.
 *
 * \{
 */

/*!
 * \brief Generic PicoGUI event structure
 * 
 * The pgEvent structure can describe any PicoGUI event. A pointer to
 * a pgEvent structure is the standard way of representing an event in
 * PicoGUI.
 * 
 * The type, from, and extra members are valid in any event. The union, e,
 * contains possible formats the event's parameters may take. Only one is
 * valid, and this depends on the type of event. For example, if
 * <tt>event->type == PG_WE_PNTR_DOWN</tt>, 
 * \p event->e.pntr is valid and the mouse coordinates can be found in 
 * \p event->e.pntr.x and \p event->e.pntr.y .
 * 
 * \sa pgBind, pgGetEvent
 */
struct pgEvent {
   s16 type;      //!< Event type, a PG_WE_* or PG_NWE_* constant
   pghandle from;   //!< The widget the event was recieved from (if applicable)
   void *extra;     //!< Extra data passed to the event handler via pgBind
   
   //! Event-specific parameters
   union {
      
      //! The generic parameter. Currently unused.
      u32 param;
      
      //! Width and height, for PG_WE_BUILD and PG_WE_RESIZE
      struct {
	 s16 w;
	 s16 h;
      } size;

      //! Modifiers and key, for keyboard events
      struct {
	 s16 mods;  //!< PGMOD_* constants logically or'ed together
	 /*! 
	  * For PG_WE_KBD_CHAR, an ASCII/Unicode character. For 
	  * PG_WE_KBD_KEYUP and PG_WE_KBD_KEYDOWN, it is a PGKEY_* constant
	  */
	 s16 key;
      } kbd;
      
      //! Pointing device information, for PG_WE_PNTR_* and PG_NWE_PNTR_* events
      struct {
	 s16 x,y;
	 s16 btn;    //!< Bitmask of pressed buttons, left button is bit 0
	 s16 chbtn;  //!< Bitmask of buttons changed since last event
      } pntr;
      
      //! Streamed data, from the PG_WE_DATA event
      struct {
	 u32 size;
	 /*! Allocated and freed by the client library. It is only valid
	  * until the event handler returns or the client calls pgGetEvent */
	 char *pointer; 

	 //! Client-side representation of a pgserver trigger, for client-side input filters
	 union pg_client_trigger *trigger;
      } data;
      
   } e;
};

//! A wildcard value for pgBind()
#define PGBIND_ANY      -1

//! A wildcard value for pgNewFont
#define PGFONT_ANY      0

/*! 
 * \brief RGB hardware-independant color
 * 
 * The format is 24-bit RGB, similar to that used by HTML.
 * The following are some example colors:
 * \code
#define BLACK   0x000000
#define WHITE   0xFFFFFF
#define GREY    0x808080
#define RED     0xFF0000
#define GREEN   0x00FF00
#define BLUE    0x0000FF
#define YELLOW  0xFFFF00
 * \endcode
 * 
 * Video drivers may define other formats that are selected by
 * setting a bit in the color's high byte. For example, in text-mode
 * drivers, a high byte set to 0x20 would indicate a raw character code.
 * Using the  driver, the expression (0x20000F00 | 'A') would be
 * a capital "A" with a white foreground and black background.
 * These formats are video-driver dependant, and under normal circumstances
 * the high byte should always be zero.
 */
typedef u32 pgcolor;

/*! 
 * \brief Refer to the default widget handle
 * 
 * A more verbose way of using the default widget or rship (widget
 * relationship) in PicoGUI function calls. Just using 0 is
 * perfectly acceptable, but this can make your code easier to
 * read. 
 *
 * PGDEFAULT can be used any time PicoGUI expects a widget handle, as sort
 * of a pronoun referring to most recently created widget. 
 * (the "default widget") This includes the
 * result of pgNewWidget calls, pgRegisterApp, and pgNewPopup. When PGDEFAULT
 * (or zero) is used in place of the parent and widget relationship in
 * pgNewWidget the new widget is placed after the default widget. The only
 * exception to this is when the default widget is a root widget (created with
 * pgRegisterApp or pgNewPopup) in which case the new widget is placed inside
 * the default widget.
 * 
 * \sa pgNewWidget, pgRegisterApp, pgNewPopup, pgSetWidget
 */
#define PGDEFAULT       0

//! For forming fractions, such as the size when PG_SZMODE_CNTFRACT is used
#define pgFraction(n,d) (((n)<<8)|(d))

/*!
 * \brief The event handler used in pgBind
 * 
 * \param evt The event that triggered this handler
 * \returns Zero to continue on with other handlers, nonzero to abort further event processing
 */
typedef int (*pgevthandler)(struct pgEvent *evt);
//! The event handler for pgSetIdle
typedef void (*pgidlehandler)(void);
#ifdef FD_SET
//! The event hander for pgCustomizeSelect
typedef int (*pgselecthandler)(int n, fd_set *readfds, fd_set *writefds,
			       fd_set *exceptfds, struct timeval *timeout);
typedef void (*pgselectbh)(int result, fd_set *readfds, fd_set *writefds,
			   fd_set *exceptfds);
#endif
//! Filter function for pgFilePicker()
typedef int (*pgfilter)(const char *string,const char *pattern);

#define PG_FILE_SAVEBTN    (1<<0)  //!< Use a 'save' button instead of 'open'
#define PG_FILE_MUSTEXIST  (1<<1)  //!< The chosen file must already exist
#define PG_FILE_MUSTWRITE  (1<<2)  //!< The file must be writeable
#define PG_FILE_MUSTREAD   (1<<3)  //!< The file must be readable
#define PG_FILE_SHOWDOT    (1<<4)  //!< Show . and .. directories
#define PG_FILE_SHOWHIDDEN (1<<5)  //!< Show hidden files
#define PG_FILE_SHOWBAK    (1<<6)  //!< Show editor backups
#define PG_FILE_SHOWDEV    (1<<7)  //!< Show device nodes (dangerous)
#define PG_FILE_FIELD      (1<<8)  //!< The user can enter filenames in a field

//! Default flags for a file open dialog box
#define PG_FILEOPEN     PG_FILE_MUSTREAD
//! Default flags for a file save dialog box
#define PG_FILESAVE    (PG_FILE_SAVEBTN | PG_FILE_FIELD)

/* Constants for the message dialog box flags */
#define PG_MSGBTN_OK        0x0001
#define PG_MSGBTN_CANCEL    0x0002
#define PG_MSGBTN_YES       0x0004
#define PG_MSGBTN_NO        0x0008
#define PG_MSGICON_ERROR    0x0010
#define PG_MSGICON_MESSAGE  0x0020
#define PG_MSGICON_QUESTION 0x0040
#define PG_MSGICON_WARNING  0x0080

#define PG_MSGBTNMASK       (PG_MSGBTN_OK|PG_MSGBTN_CANCEL|\
                             PG_MSGBTN_YES|PG_MSGBTN_NO)
#define PG_MSGICONMASK      (PG_MSGICON_ERROR|PG_MSGICON_MESSAGE|\
                             PG_MSGICON_QUESTION|PG_MSGICON_WARNING)

/*!
 * \brief A structure representing data, loaded or mapped into memory
 * 
 * This is returned by the pgFrom* series of functions for loading
 * data, and used by many PicoGUI functions that need to refer to a chunk of data.
 * 
 * \internal
 * 
 * \sa pgFromFile, pgFromStream, pgFromMemory, pgFromTempMemory, pgNewBitmap, pgLoadTheme
 */
struct pgmemdata {
  void *pointer;       //!< when null, indicates error
  u32 size;  //!< size in bytes of data block
  int flags;           //!< PGMEMDAT_* flags or'ed together
};
#define PGMEMDAT_NEED_FREE    0x0001   //!< pgmemdata should be free()'d when done
#define PGMEMDAT_NEED_UNMAP   0x0002   //!< pgmemdata should be munmap()'d when done

//! \}

/******************** Administration */

/*!
 * \defgroup admin Administrative Functions
 *
 * Functions that affect the entire server, or the connection between client
 * and server. Includes pgInit, error handling, and exclusive access
 *
 * \{
 */

/*!
 * \brief Initialize PicoGUI
 * 
 * See if there are any command line args relevant to PicoGUI
 * (such as for setting the PicoGUI server) and establish
 * a connection to the server. This must be the first PicoGUI
 * call in the client, and it should almost certainly be called before
 * and command line processing.
 * 
 * pgInit processes command line arguments beginning with "--pg" and removes
 * them from the argument list and terminates argv[] with a NULL. This is
 * compatible with optarg and probably other argument-processing systems.
 * Currently the following arguments are handled:
 * 
 *  - --pgserver <server>\n
 *    Connects to the PicoGUI server specified in <server>
 *  - --version \n
 *    Prints the client library version
 * 
 * Unrecognized commands beginning with "--pg" display a list of available
 * commands. If it is unable to contact the server, a client error is
 * triggered.
 *
 * The client does not need to explicitly disconnect from the PicoGUI server
 * 
 * \sa pgRegisterApp, pgSetErrorHandler
 */
void pgInit(int argc, char **argv);

/*!
 * \brief Replace the default error handler
 * 
 * \param handler A pointer to the new handler function
 * \param errortype The general type of error, a PG_ERRT_* constant
 * \param msg A message string with more information
 * 
 * Errors can be triggered by the client (in the case of an IO error or fatal signal) 
 * or by the server. (A bug somewhere, out of memory, etc.)
 * 
 * The default error handler displays a message dialog allowing the user to optionally
 * terminate the program. If it is unable to display the message dialog, the error is
 * printed to stderr and the program is terminated.
 *
 * \sa pgInit, pgErrortypeString
 */
void pgSetErrorHandler(void (*handler)(u16 errortype,
				       const char *msg));

/*!
 * \brief Load an input driver by name and return a handle
 *
 * \param name Driver name as reported by 'pgserver -l'
 *
 * \returns A handle to the loaded driver
 */
pghandle pgLoadDriver(const char *name);

/*! 
 * \brief Convert a numerical errortype to a string
 * 
 * \param errortype A PG_ERRT_* error type constant
 * 
 * \returns A pointer to the corresponding string constant
 */
const char *pgErrortypeString(u16 errortype);

/*!
 * \brief Set a handler to be called periodically
 * 
 * \param t Maximum number of milliseconds to wait between calls to handler
 * \param handler Pointer to a handler function, or NULL to disable 
 * 
 * \returns Pointer to the previous handler function
 * 
 * This is based on the pgSetnonblocking code added by Philippe, but
 * this fits the event-driven model better, and most importantly it
 * handles stopping and starting the event loop automatically.
 * Note that it is still possible for PicoGUI to block if the server
 * sends a partial reply packet, but even if the idle handler were called
 * during this time the network connection would be 'jammed' so there wouldn't
 * be much point.
 * 
 * \sa pgEventLoop
 */
pgidlehandler pgSetIdle(s32 t, pgidlehandler handler); 

/*!
 * \brief Flush all unsent request packets to the server
 * 
 * Usually this is handled automatically, but
 * it is needed in some situations. For example, a remote input driver
 * that has no real event loop, but needs to send keyboard or mouse events.
 * The events would not actually be sent to the server until pgFlushRequests
 * is called.
 * 
 * \sa pgUpdate
 */