Mercurial > pidgin3 / file revision

/*
 * Purple - Internet Messaging Library
 * Copyright (C) Pidgin Developers <devel@pidgin.im>
 *
 * Purple is the legal property of its developers, whose names are too numerous
 * to list here.  Please refer to the COPYRIGHT file distributed with this
 * source distribution.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, see <https://www.gnu.org/licenses/>.
 */

#if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION)
# error "only <purple.h> may be included directly"
#endif

#ifndef PURPLE_REQUEST_PAGE_H
#define PURPLE_REQUEST_PAGE_H

#include <stdlib.h>

#include <glib.h>
#include <glib-object.h>

/**
 * PurpleRequestPage:
 *
 * Multiple fields request data.
 */
typedef struct _PurpleRequestPage PurpleRequestPage;

#include "account.h"
#include "purplerequestgroup.h"
#include "purplerequestfield.h"

G_BEGIN_DECLS

#define PURPLE_TYPE_REQUEST_PAGE (purple_request_page_get_type())
G_DECLARE_FINAL_TYPE(PurpleRequestPage, purple_request_page,
                     PURPLE, REQUEST_PAGE, GObject)

/**
 * purple_request_page_new:
 *
 * Creates a page of fields to pass to [func@Purple.request_fields].
 *
 * Returns: (transfer full): The new request page.
 */
PurpleRequestPage *purple_request_page_new(void);

/**
 * purple_request_page_add_group:
 * @page: The fields page.
 * @group: (transfer full): The group to add.
 *
 * Adds a group of fields to the list.
 */
void purple_request_page_add_group(PurpleRequestPage *page, PurpleRequestGroup *group);

/**
 * purple_request_page_get_groups:
 * @page: The fields page.
 *
 * Returns a list of all groups in a field list.
 *
 * Returns: (element-type PurpleRequestGroup) (transfer none): A list of groups.
 */
GList *purple_request_page_get_groups(PurpleRequestPage *page);

/**
 * purple_request_page_exists:
 * @page: The fields page.
 * @id: The ID of the field.
 *
 * Returns whether or not the field with the specified ID exists.
 *
 * Returns: TRUE if the field exists, or FALSE.
 */
gboolean purple_request_page_exists(PurpleRequestPage *page, const char *id);

/**
 * purple_request_page_get_required:
 * @page: The fields page.
 *
 * Returns a list of all required fields.
 *
 * Returns: (element-type PurpleRequestField) (transfer none): The list of required fields.
 */
const GList *purple_request_page_get_required(PurpleRequestPage *page);

/**
 * purple_request_page_get_validatable:
 * @page: The fields page.
 *
 * Returns a list of all validated fields.
 *
 * Returns: (element-type PurpleRequestField) (transfer none): The list of validated fields.
 */
const GList *purple_request_page_get_validatable(PurpleRequestPage *page);

/**
 * purple_request_page_is_field_required:
 * @page: The fields page.
 * @id: The field ID.
 *
 * Returns whether or not a field with the specified ID is required.
 *
 * Returns: TRUE if the specified field is required, or FALSE.
 */
gboolean purple_request_page_is_field_required(PurpleRequestPage *page, const char *id);

/**
 * purple_request_page_all_required_filled:
 * @page: The fields page.
 *
 * Returns whether or not all required fields have values.
 *
 * Returns: TRUE if all required fields have values, or FALSE.
 */
gboolean purple_request_page_all_required_filled(PurpleRequestPage *page);

/**
 * purple_request_page_all_valid:
 * @page: The fields page.
 *
 * Returns whether or not all fields are valid.
 *
 * Returns: TRUE if all fields are valid, or FALSE.
 */
gboolean purple_request_page_all_valid(PurpleRequestPage *page);

/**
 * purple_request_page_get_field:
 * @page: The fields page.
 * @id: The ID of the field.
 *
 * Return the field with the specified ID.
 *
 * Returns: (transfer none): The field, if found.
 */
PurpleRequestField *purple_request_page_get_field(PurpleRequestPage *page, const char *id);

/**
 * purple_request_page_get_string:
 * @page: The fields page.
 * @id: The ID of the field.
 *
 * Returns the string value of a field with the specified ID.
 *
 * Returns: The string value, if found, or %NULL otherwise.
 */
const char *purple_request_page_get_string(PurpleRequestPage *page, const char *id);

/**
 * purple_request_page_get_integer:
 * @page: The fields page.
 * @id: The ID of the field.
 *
 * Returns the integer value of a field with the specified ID.
 *
 * Returns: The integer value, if found, or 0 otherwise.
 */
int purple_request_page_get_integer(PurpleRequestPage *page, const char *id);

/**
 * purple_request_page_get_bool:
 * @page: The fields page.
 * @id: The ID of the field.
 *
 * Returns the boolean value of a field with the specified ID.
 *
 * Returns: The boolean value, if found, or %FALSE otherwise.
 */
gboolean purple_request_page_get_bool(PurpleRequestPage *page, const char *id);

/**
 * purple_request_page_get_choice:
 * @page: The fields page.
 * @id:     The ID of the field.
 *
 * Returns the choice index of a field with the specified ID.
 *
 * Returns: The choice value, if found, or NULL otherwise.
 */
gpointer purple_request_page_get_choice(PurpleRequestPage *page, const char *id);

/**
 * purple_request_page_get_account:
 * @page: The fields page.
 * @id:     The ID of the field.
 *
 * Returns the account of a field with the specified ID.
 *
 * Returns: (transfer none): The account value, if found, or %NULL otherwise.
 */
PurpleAccount *purple_request_page_get_account(PurpleRequestPage *page, const char *id);

/**
 * purple_request_page_get_ui_data:
 * @page: The fields page.
 *
 * Returns the UI data associated with this object.
 *
 * Returns: The UI data associated with this object.  This is a
 *         convenience field provided to the UIs--it is not
 *         used by the libpurple core.
 */
gpointer purple_request_page_get_ui_data(PurpleRequestPage *page);

/**
 * purple_request_page_set_ui_data:
 * @page: The fields page.
 * @ui_data: A pointer to associate with this object.
 *
 * Set the UI data associated with this object.
 */
void purple_request_page_set_ui_data(PurpleRequestPage *page, gpointer ui_data);

G_END_DECLS

#endif /* PURPLE_REQUEST_PAGE_H */