1 /* Monolith user directory widget.
2 * - by Richard W.M. Jones <rich@annexia.org>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the Free
16 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 * $Id: ml_user_directory.h,v 1.2 2003/02/22 15:34:33 rich Exp $
21 #ifndef ML_USER_DIRECTORY_H
22 #define ML_USER_DIRECTORY_H
29 struct ml_user_directory;
30 typedef struct ml_user_directory *ml_user_directory;
32 /* Function: new_ml_user_directory - monolith user directory widget
33 * Function: ml_user_directory_get_selection
34 * Function: ml_user_directory_set_selection
35 * Function: ml_user_directory_set_callback
37 * The user directory is a widget for picking a user on the system.
38 * It is very primitive at the moment, but in the future will become
39 * more advanced (able to cope with 100s-millions of people in the
40 * directory) with search features and so on.
42 * The user directory supports picking single users only at the moment,
43 * but we intend to extend it in future to support picking multiple
46 * The user directory can be used either a form input or as a
47 * standalone widget which works rather like a button.
49 * It requires the schema in @code{sql/ml_userdir_create.sql}.
51 * @code{new_ml_user_directory} creates a new user directory widget.
52 * The @code{pool}, @code{session} and @code{conninfo} arguments point
53 * to a pool for allocations, the current session and a database
54 * connection string. The @code{form} argument may be either a form
55 * object (see @ref{new_ml_form(3)}), or @code{NULL} if this widget is
56 * not going to be used in a form. @code{userid} is the initially
57 * selected user ID, or it may be @code{0} meaning that no user is
60 * @code{ml_user_directory_(get|set)_selection} reads or changes the
61 * currently selected user ID.
63 * @code{ml_user_directory_set_callback} sets a function which is
64 * called when the currently selected user is changed. Callbacks
65 * should only be set when the widget is NOT in a form.
67 * When the widget is used in a form, then the currently selected user
68 * ID is only available when the form is submitted (ie. in the form's
69 * callback function). When the widget is not in a form, then you can
70 * set a callback for the widget, and call
71 * @code{ml_user_directory_get_selection} during this function.
73 extern ml_user_directory new_ml_user_directory (pool pool, ml_session session, const char *conninfo, ml_form form, int userid);
74 extern int ml_user_directory_get_selection (ml_user_directory w);
75 extern void ml_user_directory_set_selection (ml_user_directory w, int userid);
76 extern void ml_user_directory_set_callback (ml_user_directory w, void (*fn) (ml_session, void *), ml_session session, void *data);
78 #endif /* ML_USER_DIRECTORY_H */