ui.h File Reference

#include <clist.h>
#include "ui-types.h"
#include "xetpan.h"
#include "message-types.h"
#include "mta.h"

Include dependency graph for ui.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Compounds
union	XePUIComposeWindow_u
struct	XePUIComposeWindowAny_s
union	XePUIMessageView_u
struct	XePUIMessageViewAny_s
Typedefs
typedef XePUIMessageViewAny_s	XePUIMessageViewAny
typedef XePUIComposeWindowAny_s	XePUIComposeWindowAny
Functions
XePUI *	a_UI_new (void)
void	a_UI_free (XePUI *ui)
int	a_UI_id_editor_is_locked (void)
int	a_UI_id_editor_lock (void)
void	a_UI_id_editor_unlock (void)
int	a_UI_init (XetPan *xetpan, int *argc, char ***argv)
void	a_UI_main (XetPan *xetpan)
void	a_UI_main_quit (XetPan *xetpan)
int	a_UI_main_switch (XetPan *xetpan, const char *terminal, int uitype)
int	a_UI_events_pending (XetPan *xetpan)
void	a_UI_main_iteration (XetPan *xetpan)
void	a_UI_wait_until (XetPan *xetpan, int *semaphore, int value)
void	a_UI_first_launch (XetPan *xetpan)
void	a_UI_compose_pending_requests (XetPan *xetpan)
XePUIMain *	a_UI_mainview_new (void)
XePUIComposeWindow *	a_UI_composewindow_new (void)
XePUIMessageView *	a_UI_messageview_new (void)
XePUIMain *	a_UI_mainview_create (XetPan *xetpan, char *terminal, int type)
int	a_UI_close_all (XetPan *xetpan, int uitype)
int	a_UI_mainview_close (XePUIMain *uimain)
int	a_UI_mainview_close_all (XetPan *xetpan, int uitype)
void	a_UI_foldersview_list_updated (void)
void	a_UI_foldersview_list_refresh (void)
void	a_UI_expunge_folder (const char *ref)
void	a_UI_update_folder (const char *ref)
void	a_UI_folder_updated (void *anull, void *afolder)
void	a_UI_refresh_folder (const char *ref)
void	a_UI_message_updated (XePMessage *message)
XePUIComposeWindow *	a_UI_composewindow_create (XetPan *xetpan, char *terminal, int type)
XePUIComposeWindow *	a_UI_composewindow_compose (XetPan *xetpan, char *terminal, int type, const char *mailto)
XePUIComposeWindow *	a_UI_composewindow_reply (XetPan *xetpan, char *terminal, int uitype, XePMessage *message, const char *reply_text, const char *reply_charset)
XePUIComposeWindow *	a_UI_composewindow_forward (XetPan *xetpan, char *terminal, int uitype, XePMessage *message)
XePUIComposeWindow *	a_UI_composewindow_redirect (XetPan *xetpan, char *terminal, int uitype, XePMessage *message)
void	a_UI_composewindow_set_message (XePUIComposeWindow *uicompose, XePMessage *message)
void	a_UI_composewindow_set_mailto (XePUIComposeWindow *uicompose, const char *mailto)
void	a_UI_composewindow_set_body_text (XePUIComposeWindow *uicompose, const char *text, size_t text_size, const char *text_charset)
void	a_UI_composewindow_add_header (XePUIComposeWindow *uicompose, XePMessageHeaderType header_type, const char *header_name, const char *header_value)
int	a_UI_composewindow_close (XePUIComposeWindow *uicompose)
int	a_UI_composewindow_close_all (XetPan *xetpan, int uitype)
XePUIMessageView *	a_UI_messageview_create (XetPan *xetpan, char *terminal, int uitype)
int	a_UI_messageview_close (XePUIMessageView *viewer)
int	a_UI_messageview_close_all (XetPan *xetpan, int uitype)
void	a_UI_messageview_view_file (XePUIMessageView *mview, char *filename)
void	a_UI_notify_error (XetPan *xetpan)
void	a_UI_notify_error_reset (XetPan *xetpan)
void	a_UI_folder_messages_change_flags (XePFolder *folder, carray *messages)
void	a_UI_messageview_show_message (XePUIMessageView *mview, XePMessage *message)
void	a_UI_messageview_fetch_show_async (XePUIMessageView *mview, XePMessage *message)
void	a_UI_messageview_finalize (XePUIMessageView *mview, XePMessage *message)
void	a_UI_messageview_flags_change_async (XePUIMessageView *mview, XePMessage *message)
void	a_UI_messageview_mime_view_show (XetPan *xetpan, XePMessage *message)
void	a_UI_messageview_mime_view_block (XetPan *xetpan, XePMessage *message)
void	a_UI_messageview_mime_view_unblock (XetPan *xetpan, XePMessage *message)
void	a_UI_messageview_mime_fetch_show_selected_async (XePUIMessageView *mview, XePMessage *message)
void	a_UI_messageview_mime_show_selected (XePUIMessageView *mview, XePMessage *message)
void	a_UI_send_cmd_result (XetPan *xetpan)
unsigned int	a_UI_add_io_watch (XetPan *xetpan, int fd, short int condition, void(*callback)(int afd, short int acondition, void *adata), void *data)
int	a_UI_remove_io_watch (XetPan *xetpan, unsigned int watch_id)
Variables
const char *	A_UI_ABOUT_AUTHORS
const char *	A_UI_ABOUT_LICENSE
const char *	A_UI_ABOUT_HOME_PAGE
const char *	A_UI_ABOUT_COPYRIGHT

---

Typedef Documentation

typedef struct XePUIComposeWindowAny_s XePUIComposeWindowAny

typedef struct XePUIMessageViewAny_s XePUIMessageViewAny

---

Function Documentation

unsigned int a_UI_add_io_watch (  XetPan *  xetpan, int  fd, short int  condition, void(*  callback)(int afd, short int acondition, void *adata), void *  data )

Add a handler when traffic occurs on a file descriptor Parameters: xetpan  the main XetPan structure fd  the file descriptor to watch condition  type of conditio to watch XETPAN_IO_WATCH_READ, XETPAN_IO_WATCH_WRITE or XETPAN_IO_WATCH_EXCEPTION callback  a function that is fed with the file descriptor, the condition occured and the supplied user data and that must return non zero to stop watching data  the user supplied data that will be passed to the callback Returns: the unique ID that can be used to stop watching.

int a_UI_close_all (  XetPan *  xetpan, int  uitype )

Close all UIs (windows) of a given UI type This function will close all windows/screens corresponding to a certain UI type. The windows/screens are the main views and the compose windows. TODO: add also the standalone message views. Parameters: xetpan  the main XetPan structure uitype  the UI type of which the windows are to be closed Returns: 1 if no more UI window/screen of any type is open, 0 otherwise

Here is the call graph for this function:

void a_UI_compose_pending_requests (  XetPan *  xetpan  )

void a_UI_composewindow_add_header (  XePUIComposeWindow *  uicompose, XePMessageHeaderType  header_type, const char *  header_name, const char *  header_value )

int a_UI_composewindow_close (  XePUIComposeWindow *  uicompose  )

Here is the call graph for this function:

int a_UI_composewindow_close_all (  XetPan *  xetpan, int  uitype )

Here is the call graph for this function:

XePUIComposeWindow* a_UI_composewindow_compose (  XetPan *  xetpan, char *  terminal, int  type, const char *  mailto )

Create a new window to compose a new message This function creates a new window and prepares it for a new message to compose Parameters: xetpan  the main XetPan structure terminal  the terminal/display where the window is to be opened uitype  the UI type mailto  a mailto URL to prefill differents parts of the new message Returns: a newly allocated and registered XePUIComposeWindow compose window structure

Here is the call graph for this function:

XePUIComposeWindow* a_UI_composewindow_create (  XetPan *  xetpan, char *  terminal, int  type )

Create a new compose window. This function calls the UI specific composewindow_create() and register the newly created instance of XePUIComposeWindow. This function should not be called directly as it does not take care of creating the underlying XePMessage structure. Use one of the a_UI_composewindow_(compose|reply|forward|redirect)() Parameters: xetpan  the main XetPan structure terminal  the terminal/display on which the window is to be shown (same syntax as for a_UI_mainview_create()) type  the UI type Returns: a newly created instance of XePUIComposeWindow compose window structure.

XePUIComposeWindow* a_UI_composewindow_forward (  XetPan *  xetpan, char *  terminal, int  uitype, XePMessage *  message )

Here is the call graph for this function:

XePUIComposeWindow* a_UI_composewindow_new (  void   )

Create and register a new XePUIComposeWindow structure This functions creates a new instance of a XePUIComposeWindow structure used to represent a compose window. Contrary to a_UI_mainview_new(), it does not register it. a_UI_composewindow_create() does it instead. This will be changed in the future.

XePUIComposeWindow* a_UI_composewindow_redirect (  XetPan *  xetpan, char *  terminal, int  uitype, XePMessage *  message )

Here is the call graph for this function:

XePUIComposeWindow* a_UI_composewindow_reply (  XetPan *  xetpan, char *  terminal, int  uitype, XePMessage *  message, const char *  reply_text, const char *  reply_charset )

Create a new window to compose a reply This function creates a new window to reply to a an existant message Parameters: xetpan  the main XetPan structure terminal  the terminal/display where the window is to be opened uitype  the UI type original_message  the original message to which the reply is created reply_text  eventually the text to be quoted for the reply. The UI may decide to provide its own text derived or not from the original message text reply_charset  the character set of the reply_text Returns: a newly allocated and registered XePUIComposeWindow compose window structure

Here is the call graph for this function:

void a_UI_composewindow_set_body_text (  XePUIComposeWindow *  uicompose, const char *  text, size_t  text_size, const char *  text_charset )

void a_UI_composewindow_set_mailto (  XePUIComposeWindow *  uicompose, const char *  mailto )

Here is the call graph for this function:

void a_UI_composewindow_set_message (  XePUIComposeWindow *  uicompose, XePMessage *  message )

Set the XePMessage to be edited. This function makes the specified compose window edit the given XePMessage

int a_UI_events_pending (  XetPan *  xetpan  )

Check if there are some events that wait to be handled This function calls the specific UI function events_pending(); Parameters: xetpan  the main XetPan structure Returns: 0 if no event is pending, 1 if some are waiting

void a_UI_expunge_folder (  const char *  ref  )

Expunge a folder then call a_UI_update_folder() This function requests the threads manager to update a folder. When thread finishes its work (the folder is updated), a_UI_folder_updated() is called If the request is done for an unknown folder, this functions issues an error message and returns without doing anything else. Parameters: xetpan  the main XetPan structure ref  the ID of the folder to update

Here is the call graph for this function:

void a_UI_first_launch (  XetPan *  xetpan  )

Show the welcome window when the user launches XetPan for the first time This function is called when no configuration file is found. It greets the user and proposes to configure XetPan. After that, it should open a new main view or proceed with the composition of messages if the -c command switch was given. It calls the UI specific first_launch() function Parameters: xetpan  the main XetPan structure

void a_UI_folder_messages_change_flags (  XePFolder *  folder, carray *  messages )

Submit job to change flags of an array of messages pertaining to a (REAL) folder Parameters: folder  the folder containing the messages messages  an array of messages

Here is the call graph for this function:

void a_UI_folder_updated (  void *  anull, void *  afolder )

Update each UI that is displaying the given folder This functions checks each main view if it is currently displaying the folder, in which case it will call the UI specific folder_updated() function on that main view Parameters: axetpan  the main XetPan structure afolder  the folder that was updated

void a_UI_foldersview_list_refresh (  void   )

Refresh foldersview list data

void a_UI_foldersview_list_updated (  void   )

Notify all UI that foldersview list has been changed and reselect the summaryview

void a_UI_free (  XePUI *  ui  )

Frees the main UI structure. Frees only the resources it directly uses

int a_UI_id_editor_is_locked (  void   )

Check if there is already an Id editor running Returns: 1 if an Id editor is already running, 0 otherwise

int a_UI_id_editor_lock (  void   )

Set the Id editor flag, meaning an Id editor is being run Returns: 0 if lock succeeded, non 0 if the flag was alread locked

void a_UI_id_editor_unlock (  void   )

Unset the Id editor flag This function always succeeds

int a_UI_init (  XetPan *  xetpan, int *  argc, char ***  argv )

UI Initialization : If UI type in XetPan::ui::type is specified, run only that UI and abort XetPan if an error occurs. If no UI type is specified, use the first registered UI (currently GTK, TTY). If no UI could be initialized, display a message error. Parameters: xetpan  the mani XetPan structure that has its ui member defined. Returns: 0 on success and -1 if an error occured (no UI)

void a_UI_main (  XetPan *  xetpan  )

UI main loop This function is called once and for all to run the UI main loop. It returns only when XetPan is to be exited. It handles internally the UI switching (from TTY->GTK or from GTK->TTY) When a UI switch is requested, it calls initializes it and creates a new main view, then it run the UI specific event loop. Parameters: xetpan  the main XetPan structure

Here is the call graph for this function:

void a_UI_main_iteration (  XetPan *  xetpan  )

Run a single iteration of the event loop This function will wait for the first events and will process them by calling the appropriate associated callbacks Parameters: xetpan  the main XetPan structure

void a_UI_main_quit (  XetPan *  xetpan  )

Ends the current UI event loop This amounts to calling a_UI_main_switch() with the XETPAN_UI_QUIT UI type. Parameters: xetpan  the main XetPan structure

Here is the call graph for this function:

int a_UI_main_switch (  XetPan *  xetpan, const char *  terminal, int  uitype )

Request a UI switch This function is to be called when the user switches from a UI event loop to another. Note that GTK event loop handles TTY events, but TTY event loop can't handle GTK events. When the same UI type as the current one is requested, nothing is done. The switch from TTY->GTK is needed when the user request a graphical interface. The switch from TTY->GTK is needed when the user will loose a graphical interface. (In the future, XetPan will be able to run in daemon mode) The switch is done by quitting the UI specifig event loop, and setting the UI switch flag. This function is also called by a_UI_main_quit() to quit XetPan, in which case it frees all IO handlers Parameters: xetpan  the main XetPan structure terminal  the terminal/display where the new UI is to be opened uitype  the type of the new UI (XETPAN_UI_TTY, XETPAN_UI_GTK or XETPAN_UI_QUIT to quit. Returns: 0 always...

int a_UI_mainview_close (  XePUIMain *  uimain  )

Close a main view This function closes the given main view, by removing it from the list of available main views and by calling the UI specifig mainview_close() function. Parameters: uimain  the specific main view to close Returns: 1 if there are no more UI windows/screens, 0 other wise

Here is the call graph for this function:

int a_UI_mainview_close_all (  XetPan *  xetpan, int  uitype )

Close all main views of a given UI type This function will successively close all the main views of a certain UI type Parameters: xetpan  the main xetpan structure uitype  the UI type of which the main views are to be closed Returns: if there are no more UI windows/screens, 0 other wise

Here is the call graph for this function:

XePUIMain* a_UI_mainview_create (  XetPan *  xetpan, char *  terminal, int  type )

Create a new main view This function creates a new main view. A main view is the main user interface that provide access to all XetPan functionalities. It allows to select folder, view a summary of the messages, view a message, run scripts, configure XetPan etc. Parameters: xetpan  the main XetPan structure terminal  the terminal/display on which the main view is to be displayed. For X based UI, this corresponds to the display and has the same format as the $DISPLAY environment variable. $DISPLAY can be NULL, in which case the GUI is responsible of using an appropriate display. For a TTY based UI, terminal consists of the terminal description in the same format as the $TERM environment variable along with the a tty path in the same format as returned by the ttyname() function, both elements being separated by a HTAB character (). If the terminal argument is NULL, the TTY interface will select the terminal bound to stdin and will get the terminal description from the $TERM environment variable type  the UI type Returns: a newly allocated and registered XePUIMain. The main view has to be functional as soon as the UI event loop is started.

XePUIMain* a_UI_mainview_new (  void   )

Create and register a new XePUIMain main view structure This function creates a new instance of the XePUIMain main view structure and registers it in the static global_mainviews table.

void a_UI_message_updated (  XePMessage *  message  )

Update each UI that would be modified if the given message has changed state (flags) Function to call when flags of message have changed Parameters: message  the message that was modified

int a_UI_messageview_close (  XePUIMessageView *  viewer  )

Here is the call graph for this function:

int a_UI_messageview_close_all (  XetPan *  xetpan, int  uitype )

Here is the call graph for this function:

XePUIMessageView* a_UI_messageview_create (  XetPan *  xetpan, char *  terminal, int  uitype )

Create a standalone message viewer

void a_UI_messageview_fetch_show_async (  XePUIMessageView *  mview, XePMessage *  message )

Fetch a message and show it when available This function will request a thread to fetch a message, to find the default MIME part to show, to fetch that MIME part after which a first UI callback will show that MIME part, a second one will asynchronously set the SEEN and unset the NEW flags of the message, and the third one

void a_UI_messageview_finalize (  XePUIMessageView *  mview, XePMessage *  message )

void a_UI_messageview_flags_change_async (  XePUIMessageView *  mview, XePMessage *  message )

Change a message's flag and flush The XePMessage::flags_set and XePMessage::flags_unset must be set accordingly. This function will use a thread to change the flags Before setting them, all message views of the message are requested to block the mime view because their data will be invalidated by the mailmessage_flush. When the thread finishes its jobs, it will call a callback that will unblock the mime views. Parameters: uimain  the calling main window message  the message for which the flags must be changed. The flags to set are to be stored in XePMessage::flags_set and the ones to unset are to be stored in XePMessage::flags_unset Returns: no value returned, this a an asynchroneous job

Here is the call graph for this function:

void a_UI_messageview_mime_fetch_show_selected_async (  XePUIMessageView *  mview, XePMessage *  message )

Fetch then show the selected MIME part A thread is requested to fetch the message part. When it is done the actual message viewing function is called Parameters: the  XePUIMessageView requesting the job the  XePMessage that contains the selected MIME part to fetch and show Returns: no value returned

Here is the call graph for this function:

void a_UI_messageview_mime_show_selected (  XePUIMessageView *  mview, XePMessage *  message )

Show the selected message part Only the requesting XePUIMain is concerned. Parameters: the  XePUIMessageView that requested to show the MIME part message  the message that contains the selected MIME part to show Returns: no value returned

void a_UI_messageview_mime_view_block (  XetPan *  xetpan, XePMessage *  message )

Block the MIME view of a message Every UI that is currently showing this message will block its MIME view because the the MIME data are going to be invalidated Parameters: xetpan  the main data pointer message  the message which MIME view should be blocked Returns: no value returned

void a_UI_messageview_mime_view_show (  XetPan *  xetpan, XePMessage *  message )

Request showing the MIME parts of a message Every UI that is currently showing this message will update its MIME view. Parameters: xetpan  the main data pointer message  the message which MIME view should be updated Returns: no value returned

void a_UI_messageview_mime_view_unblock (  XetPan *  xetpan, XePMessage *  message )

Block the MIME view of a message Every UI that is currently showing this message will unblock its MIME view because the the MIME data are considered valid again. Parameters: xetpan  the main data pointer message  the message which MIME view should be unblocked Returns: no value returned

XePUIMessageView* a_UI_messageview_new (  void   )

Create and register a new instance of XePUIMessageView This function creates a new instance of XePUIMessageView message view structure and registers is in the static global_messageviews table.

void a_UI_messageview_show_message (  XePUIMessageView *  mview, XePMessage *  message )

Generic fuction to show a message in a message view.

Here is the call graph for this function:

void a_UI_messageview_view_file (  XePUIMessageView *  mview, char *  filename )

View a RFC822 file in a message viewer

Here is the call graph for this function:

XePUI* a_UI_new (  void   )

Create the main UI structure This function created the XePUI main structure and initializes the static array UI that points to the specific UI main functions. Returns: the newly allocated XePUI structure ready to be used. The UI state is set to 1 meaning that we are switching to a new UI (from no UI).

Here is the call graph for this function:

void a_UI_notify_error (  XetPan *  xetpan  )

void a_UI_notify_error_reset (  XetPan *  xetpan  )

void a_UI_refresh_folder (  const char *  ref  )

Here is the call graph for this function:

int a_UI_remove_io_watch (  XetPan *  xetpan, unsigned int  watch_id )

void a_UI_send_cmd_result (  XetPan *  xetpan  )

void a_UI_update_folder (  const char *  ref  )

Update a folder by rereading its content and refresh UIs that are displaying it. This function requests the threads manager to update a folder. When thread finishes its work (the folder is updated), a_UI_folder_updated() is called If the request is done for an unknown folder, this functions issues an error message and returns without doing anything else. Parameters: xetpan  the main XetPan structure ref  the ID of the folder to update

Here is the call graph for this function:

void a_UI_wait_until (  XetPan *  xetpan, int *  semaphore, int  value )

Wait for certain semaphore to have a defined value, while running the event loop This function will not return until the semaphore has that value, without blocking the user interface. This can be helpful to sequentiallize some operations without blocking the UI Parameters: xetpan  the main XetPan structure semaphore  a pointer to the variable which value is to be checked value  the value to wait for

Here is the call graph for this function:

---

Variable Documentation

const char* A_UI_ABOUT_AUTHORS

const char* A_UI_ABOUT_COPYRIGHT

const char* A_UI_ABOUT_HOME_PAGE

const char* A_UI_ABOUT_LICENSE

---