#!/usr/bin/env python3
# -*- coding: utf-8 -*-

""" xforms-python's functions to manage formbrowser flobjects.
"""

#    Copyright (C) 2009-2012  Luca Lazzaroni "LukenShiro"
#    e-mail: <lukenshiro@ngi.it>
#
#    This program 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, version 2.1 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 Lesser General Public License for more details.
#
#    You should have received a copy of the GNU LGPL along with this
#    program. If not, see <http://www.gnu.org/licenses/>.
#
#    See CREDITS file to read acknowledgements and thanks to XForms,
#    ctypes and other developers.

# originally generated by 'h2xml+gccxml' and 'xml2py'
# then heavily reordered and reworked

# ########################################### #
# Interface to XForms shared-object libraries #
# ########################################### #


import ctypes as cty
from xformslib import library
from xformslib import xfdata


##########################
# forms.h (formbrowser.h)
##########################

def fl_addto_formbrowser(ptr_flobject, ptr_flform):
    """fl_addto_formbrowser(ptr_flobject, ptr_flform) -> numforms

    Populates a formbrowser. The form so added is appended to the list of
    forms that are already in the formbrowser. Form should be valid for the
    duration of the formbrowser and the application program should not destroy
    a form that is added to a formbrowser before deleting the form from the
    formbrowser first.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        ptr_flform : pointer to xfdata.FL_FORM
            form

    Returns
    -------
        numforms : int
            total number of forms in the formbrowser

    Examples
    --------
        >>> ntotfrms = fl_addto_formbrowser(pfrmbrobj, newform)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_addto_formbrowser = library.cfuncproto(
        library.load_so_libforms(), "fl_addto_formbrowser",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT),
        cty.POINTER(xfdata.FL_FORM)],
        """int fl_addto_formbrowser(FL_OBJECT * ob, FL_FORM * form)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.verify_flformptr_type(ptr_flform)
    library.keep_elem_refs(ptr_flobject, ptr_flform)
    retval = _fl_addto_formbrowser(ptr_flobject, ptr_flform)
    return retval


def fl_delete_formbrowser_bynumber(ptr_flobject, seqnum):
    """fl_delete_formbrowser_bynumber(ptr_flobject, seqnum) -> ptr_flform

    Removes a form from the formbrowser using a sequence number, an
    integer between 1 and the number of forms in the browser. After a
    form is removed, the sequence numbers are re-adjusted so they are
    always consecutive.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        seqnum : int
            sequence number of form to be removed

    Returns
    -------
        ptr_flform : pointer to xfdata.FL_FORM
            removed form, or None (on failure)

    Examples
    --------
        >>> delfrm = fl_delete_formbrowser_bynumber(pfrmbrobj, 2)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_delete_formbrowser_bynumber = library.cfuncproto(
        library.load_so_libforms(), "fl_delete_formbrowser_bynumber",
        cty.POINTER(xfdata.FL_FORM), [cty.POINTER(xfdata.FL_OBJECT),
        cty.c_int],
        """FL_FORM * fl_delete_formbrowser_bynumber(FL_OBJECT * ob, int
           num)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    i_seqnum = library.convert_to_intc(seqnum)
    library.keep_elem_refs(ptr_flobject, seqnum, i_seqnum)
    retval = _fl_delete_formbrowser_bynumber(ptr_flobject, i_seqnum)
    return retval


def fl_delete_formbrowser(ptr_flobject, ptr_flform):
    """fl_delete_formbrowser(ptr_flobject, ptr_flform) -> numforms

    Removes a specified form from the formbrowser.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        ptr_flform : pointer to xfdata.FL_FORM
            form candidate to deletion

    Returns
    -------
        numforms : int
            current (after deletion) number of forms in the formbrowser, or
            -1 (on failure)

    Examples
    --------
        >>> numfrm = fl_delete_formbrowser(pfrmbrobj, p2ndform)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_delete_formbrowser = library.cfuncproto(
        library.load_so_libforms(), "fl_delete_formbrowser",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT),
        cty.POINTER(xfdata.FL_FORM)],
        """int fl_delete_formbrowser(FL_OBJECT * ob,
           FL_FORM * candidate_form)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.verify_flformptr_type(ptr_flform)
    library.keep_elem_refs(ptr_flobject, ptr_flform)
    retval = _fl_delete_formbrowser(ptr_flobject, ptr_flform)
    return retval


def fl_replace_formbrowser(ptr_flobject, seqnum, ptr_flform):
    """fl_replace_formbrowser(ptr_flobject, seqnum, ptr_flform) -> ptr_flform

    Replaces a form in formbrowser specified by a sequence number

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        seqnum : int
            sequence number of form to be replaced
        ptr_flform : pointer to xfdata.FL_FORM
            form used as replacement

    Returns
    -------
        ptr_flform : pointer to xfdata.FL_FORM
            form that has been replaced, or None (on failure)

    Examples
    --------
        >>> replfrm = fl_replace_formbrowser(pfrmbrobj, 4, newreplfrm)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_replace_formbrowser = library.cfuncproto(
        library.load_so_libforms(), "fl_replace_formbrowser",
        cty.POINTER(xfdata.FL_FORM), [cty.POINTER(xfdata.FL_OBJECT),
        cty.c_int, cty.POINTER(xfdata.FL_FORM)],
        """FL_FORM * fl_replace_formbrowser(FL_OBJECT * ob, int num,
           FL_FORM * form)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    i_seqnum = library.convert_to_intc(seqnum)
    library.verify_flformptr_type(ptr_flform)
    library.keep_elem_refs(ptr_flobject, seqnum, ptr_flform, i_seqnum)
    retval = _fl_replace_formbrowser(ptr_flobject, i_seqnum, ptr_flform)
    return retval


def fl_insert_formbrowser(ptr_flobject, seqnum, ptr_flform):
    """fl_insert_formbrowser(ptr_flobject, seqnum, ptr_flform) -> numforms

    Inserts a form into a formbrowser at arbitrary location.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        seqnum : int
            the sequence number before which the new form form is to be
            inserted into the formbrowser
        ptr_flform : pointer to xfdata.FL_FORM
            new form to insert

    Returns
    -------
        numforms : int
            number of forms in the formbrowser, or -1 (on failure)

    Examples
    --------
        >>> frmsnum = fl_insert_formbrowser(pfrmbrobj, 5, pform)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_insert_formbrowser = library.cfuncproto(
        library.load_so_libforms(), "fl_insert_formbrowser",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT), cty.c_int, \
        cty.POINTER(xfdata.FL_FORM)],
        """int fl_insert_formbrowser(FL_OBJECT * ob, int line,
           FL_FORM * new_form)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    i_seqnum = library.convert_to_intc(seqnum)
    library.verify_flformptr_type(ptr_flform)
    library.keep_elem_refs(ptr_flobject, seqnum, i_seqnum, ptr_flform)
    retval = _fl_insert_formbrowser(ptr_flobject, i_seqnum, ptr_flform)
    return retval


def fl_get_formbrowser_area(ptr_flobject):
    """fl_get_formbrowser_area(ptr_flobject)
    -> result, xpos, ypos, width, height

    Finds out the actual size of the form's area. The area occupied by
    the formbrowser contains the space for the scrollbars.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject

    Returns
    -------
        result : int
            1, or 0 (on failure)
        xpos : int
            horizontal position
        ypos : int
            vertical position
        width : int
            width of form's area
        height : int
            height of form's area

    Examples
    --------
        >>> exval, x, y, w, h = fl_get_formbrowser_area(pfrmbrobj)

    API_diversion
    ----------
        API changed from XForms, upstream is
        fl_get_formbrowser_area(ptr_flobject, xpos, ypos, width, height)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_get_formbrowser_area = library.cfuncproto(
        library.load_so_libforms(), "fl_get_formbrowser_area",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT), cty.POINTER(cty.c_int),
        cty.POINTER(cty.c_int), cty.POINTER(cty.c_int), \
        cty.POINTER(cty.c_int)],
        """int fl_get_formbrowser_area(FL_OBJECT * ob, int * x, int * y,
           int * w, int * h)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    i_xpos, ptr_xpos = library.make_intc_and_pointer()
    i_ypos, ptr_ypos = library.make_intc_and_pointer()
    i_width, ptr_width = library.make_intc_and_pointer()
    i_height, ptr_height = library.make_intc_and_pointer()
    library.keep_elem_refs(ptr_flobject, i_xpos, i_ypos, i_width, i_height, \
            ptr_xpos, ptr_ypos, ptr_width, ptr_height)
    retval = _fl_get_formbrowser_area(ptr_flobject, ptr_xpos, ptr_ypos, \
            ptr_width, ptr_height)
    return retval, i_xpos.value, i_ypos.value, i_width.value, i_height.value


def fl_set_formbrowser_scroll(ptr_flobject, howscroll):
    """fl_set_formbrowser_scroll(ptr_flobject, howscroll)

    Changes the vertical scrollbar so each action of the scrollbar scrolls
    to the next forms. By default it scrolls a fixed number of pixels.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        howscroll : int
            How it scrolls. Values (from xfdata.py)
            - FL_SMOOTH_SCROLL (Default scroll),
            - FL_JUMP_SCROLL (Scrolls in form increments).

    Examples
    --------
        >>> fl_set_formbrowser_scroll(pfrmbrobj, xfdata.FL_JUMP_SCROLL)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_set_formbrowser_scroll = library.cfuncproto(
        library.load_so_libforms(), "fl_set_formbrowser_scroll",
        None, [cty.POINTER(xfdata.FL_OBJECT), cty.c_int],
        """void fl_set_formbrowser_scroll(FL_OBJECT * ob, int how)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.checkfatal_allowed_value_in_list(howscroll, \
            xfdata.FORMBRWSSCROLL_list)
    i_howscroll = library.convert_to_intc(howscroll)
    library.keep_elem_refs(ptr_flobject, howscroll, i_howscroll)
    _fl_set_formbrowser_scroll(ptr_flobject, i_howscroll)


def fl_set_formbrowser_hscrollbar(ptr_flobject, howscroll):
    """fl_set_formbrowser_hscrollbar(ptr_flobject, howscroll)

    Controls the presence of horizontal scrollbar. By default, if the size of
    the forms exceeds the size of the formbrowser, scrollbars are added
    automatically.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        howscroll : int
            if scrollbar is added or not. Values (from xfdata.py)
            - FL_AUTO (On when needed, default),
            - FL_ON (always on),
            - FL_OFF (always off).

    Examples
    --------
        >>> fl_set_formbrowser_hscrollbar(pfrmbrobj, xfdata.FL_OFF)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_set_formbrowser_hscrollbar = library.cfuncproto(
        library.load_so_libforms(), "fl_set_formbrowser_hscrollbar",
        None, [cty.POINTER(xfdata.FL_OBJECT), cty.c_int],
        """void fl_set_formbrowser_hscrollbar(FL_OBJECT * ob, int how)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.checkfatal_allowed_value_in_list(howscroll, \
            xfdata.SCROLLBARVAL_list)
    i_howscroll = library.convert_to_intc(howscroll)
    library.keep_elem_refs(ptr_flobject, howscroll, i_howscroll)
    _fl_set_formbrowser_hscrollbar(ptr_flobject, i_howscroll)


def fl_set_formbrowser_vscrollbar(ptr_flobject, howscroll):
    """fl_set_formbrowser_vscrollbar(ptr_flobject, howscroll)

    Controls the presence of vertical scrollbar. By default, if the size of
    the forms exceeds the size of the formbrowser, scrollbars are added
    automatically.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        howscroll : int
            if scrollbar is added or not. Values (from xfdata.py)
            - FL_AUTO (On when needed, default),
            - FL_ON (always on),
            - FL_OFF (always off).

    Examples
    --------
        >>> fl_set_formbrowser_vscrollbar(pfrmbrobj, xfdata.FL_OFF)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_set_formbrowser_vscrollbar = library.cfuncproto(
        library.load_so_libforms(), "fl_set_formbrowser_vscrollbar",
        None, [cty.POINTER(xfdata.FL_OBJECT), cty.c_int],
        """void fl_set_formbrowser_vscrollbar(FL_OBJECT * ob, int how)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.checkfatal_allowed_value_in_list(howscroll, \
            xfdata.SCROLLBARVAL_list)
    i_howscroll = library.convert_to_intc(howscroll)
    library.keep_elem_refs(ptr_flobject, howscroll, i_howscroll)
    _fl_set_formbrowser_vscrollbar(ptr_flobject, i_howscroll)


def fl_get_formbrowser_topform(ptr_flobject):
    """fl_get_formbrowser_topform(ptr_flobject)

    Finds out the form that is currently the first form in the formbrowser
    visible to the user.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject

    Returns
    -------
        ptr_flform : pointer to xfdata.FL_FORM
            first visible form

    Examples
    --------
        >>> pform4 = fl_get_formbrowser_topform(pfrmbrobj)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_get_formbrowser_topform = library.cfuncproto(
        library.load_so_libforms(), "fl_get_formbrowser_topform",
        cty.POINTER(xfdata.FL_FORM), [cty.POINTER(xfdata.FL_OBJECT)],
        """FL_FORM * fl_get_formbrowser_topform(FL_OBJECT * ob)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.keep_elem_refs(ptr_flobject)
    retval = _fl_get_formbrowser_topform(ptr_flobject)
    return retval


def fl_set_formbrowser_topform(ptr_flobject, ptr_flform):
    """fl_set_formbrowser_topform(ptr_flobject, ptr_flform) -> seqnum

    Defines which form to show by setting the top form.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        ptr_flform : pointer to xfdata.FL_FORM
            form

    Returns
    -------
        seqnum : int
            sequence number of the form

    Examples
    --------
        >>> frmid = fl_set_formbrowser_topform(pfrmbrobj, pform)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_set_formbrowser_topform = library.cfuncproto(
        library.load_so_libforms(), "fl_set_formbrowser_topform",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT),
        cty.POINTER(xfdata.FL_FORM)],
        """int fl_set_formbrowser_topform(FL_OBJECT * ob, FL_FORM * form)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.verify_flformptr_type(ptr_flform)
    library.keep_elem_refs(ptr_flobject, ptr_flform)
    retval = _fl_set_formbrowser_topform(ptr_flobject, ptr_flform)
    return retval


def fl_set_formbrowser_topform_bynumber(ptr_flobject, seqnum):
    """fl_set_formbrowser_topform_bynumber(ptr_flobject, seqnum) -> ptr_flform

    Defines which form to show by setting the top form, using a sequence
    number.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        seqnum : int
            sequence number of form

    Returns
    -------
        ptr_flform : pointer to xfdata.FL_FORM
            new top form

    Examples
    --------
        >>> pform = fl_set_formbrowser_topform_bynumber(pfrmbrobj, 2)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_set_formbrowser_topform_bynumber = library.cfuncproto(
        library.load_so_libforms(), "fl_set_formbrowser_topform_bynumber",
        cty.POINTER(xfdata.FL_FORM), [cty.POINTER(xfdata.FL_OBJECT),
        cty.c_int],
        """FL_FORM * fl_set_formbrowser_topform_bynumber( \
           FL_OBJECT * ob, int n)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    i_seqnum = library.convert_to_intc(seqnum)
    library.keep_elem_refs(ptr_flobject, seqnum, i_seqnum)
    retval = _fl_set_formbrowser_topform_bynumber(ptr_flobject, i_seqnum)
    return retval


def fl_set_formbrowser_xoffset(ptr_flobject, offset):
    """fl_set_formbrowser_xoffset(ptr_flobject, offset) -> oldoffset

    Scrolls within a formbrowser in horizontal direction.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        offset : int
            positive number, measuring in pixels the offset from the natural
            position from the left. 0 indicates the natural position of the
            content within the formbrowser.

    Returns
    -------
        oldoffset : int
            previous horizontal offset

    Examples
    --------
        >>> num = fl_set_formbrowser_xoffset(pfrmbrobj, 15)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_set_formbrowser_xoffset = library.cfuncproto(
        library.load_so_libforms(), "fl_set_formbrowser_xoffset",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT), cty.c_int],
        """int fl_set_formbrowser_xoffset(FL_OBJECT * ob, int offset)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    i_offset = library.convert_to_intc(offset)
    library.keep_elem_refs(ptr_flobject, offset, i_offset)
    retval = _fl_set_formbrowser_xoffset(ptr_flobject, i_offset)
    return retval


def fl_set_formbrowser_yoffset(ptr_flobject, offset):
    """fl_set_formbrowser_yoffset(ptr_flobject, offset) -> oldoffset

    Scrolls within a formbrowser in vertical direction.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        offset : int
            positive number, measuring in pixels the offset from the natural
            position from the top. 0 indicates the natural position of the
            content within the formbrowser

    Returns
    -------
        oldoffset : int
            previous vertical offset

    Examples
    --------
        >>> num = fl_set_formbrowser_yoffset(pfrmbrobj, 15)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_set_formbrowser_yoffset = library.cfuncproto(
        library.load_so_libforms(), "fl_set_formbrowser_yoffset",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT), cty.c_int],
        """int fl_set_formbrowser_yoffset(FL_OBJECT * ob, int offset)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    i_offset = library.convert_to_intc(offset)
    library.keep_elem_refs(ptr_flobject, offset, i_offset)
    retval = _fl_set_formbrowser_yoffset(ptr_flobject, i_offset)
    return retval


def fl_get_formbrowser_xoffset(ptr_flobject):
    """fl_get_formbrowser_xoffset(ptr_flobject) -> offset

    Finds out the current horizontal offset from left in pixel of a
    formbrowser.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject

    Returns
    -------
        offset : int
            horizontal offset

    Examples
    --------
        >>> xoffset = fl_get_formbrowser_xoffset(pfrmbrobj)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_get_formbrowser_xoffset = library.cfuncproto(
        library.load_so_libforms(), "fl_get_formbrowser_xoffset",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT)],
        """int fl_get_formbrowser_xoffset(FL_OBJECT * ob)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.keep_elem_refs(ptr_flobject)
    retval = _fl_get_formbrowser_xoffset(ptr_flobject)
    return retval


def fl_get_formbrowser_yoffset(ptr_flobject):
    """fl_get_formbrowser_yoffset(ptr_flobject) -> offset

    Finds out the current vertical offset from top in pixel of a formbrowser.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject

    Returns
    -------
        offset : int
            vertical offset

    Examples
    --------
        >>> yoffset = fl_get_formbrowser_yoffset(pfrmbrobj)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_get_formbrowser_yoffset = library.cfuncproto(
        library.load_so_libforms(), "fl_get_formbrowser_yoffset",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT)],
        """int fl_get_formbrowser_yoffset(FL_OBJECT * ob)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.keep_elem_refs(ptr_flobject)
    retval = _fl_get_formbrowser_yoffset(ptr_flobject)
    return retval


def fl_find_formbrowser_form_number(ptr_flobject, ptr_flform):
    """fl_find_formbrowser_form_number(ptr_flobject, ptr_flform) -> seqnum

    Finds out the sequence number of a particular form.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        ptr_flform : pointer to xfdata.FL_FORM
            form candidate to be found

    Returns
    -------
        seqnum : int
            sequence number of form

    Examples
    --------
        >>> frmid = fl_find_formbrowser_form_number(pfrmbrobj, pform)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_find_formbrowser_form_number = library.cfuncproto(
        library.load_so_libforms(), "fl_find_formbrowser_form_number",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT),
        cty.POINTER(xfdata.FL_FORM)],
        """int fl_find_formbrowser_form_number(FL_OBJECT * ob,
           FL_FORM * candidate_form)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.verify_flformptr_type(ptr_flform)
    library.keep_elem_refs(ptr_flobject, ptr_flform)
    retval = _fl_find_formbrowser_form_number(ptr_flobject, ptr_flform)
    return retval


def fl_add_formbrowser(frmbrwstype, xpos, ypos, width, height, label):
    """fl_add_formbrowser(frmbrwstype, xpos, ypos, width, height, label)
    -> ptr_flform

    Adds a formbrowser flobject. It is a container class that is capable of
    holding multiple forms, the height of which in aggregate may exceed the
    screen height. The formbrowser also works obviously for a single form that
    has a height that is larger than the screen height.

    Parameters
    ----------
        frmbrwstype : int
            type of formbrowser to be added. Values (from xfdata.py)
            FL_NORMAL_FORMBROWSER (normal formbrowser type)
        xpos : int
            horizontal position (upper-left corner)
        ypos : int
            vertical position (upper-left corner)
        width : int
            width in coord units
        height : int
            height in coord units
        label : str
            text label of formbrowser

    Returns
    -------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject added

    Examples
    --------
        >>> pfrmbrobj = fl_add_formbrowser(xfdata.FL_NORMAL_FORMBROWSER,
                110, 60, 550, 750, "My Formbrowser)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_add_formbrowser = library.cfuncproto(
        library.load_so_libforms(), "fl_add_formbrowser",
        cty.POINTER(xfdata.FL_OBJECT), [cty.c_int, xfdata.FL_Coord,
        xfdata.FL_Coord, xfdata.FL_Coord, xfdata.FL_Coord, xfdata.STRING],
        """FL_OBJECT * fl_add_formbrowser(int type, FL_Coord x,
           FL_Coord y, FL_Coord w, FL_Coord h, const char * label)""")
    library.check_if_flinitialized()
    library.checkfatal_allowed_value_in_list(frmbrwstype, \
            xfdata.FORMBRWSTYPE_list)
    i_frmbrwstype = library.convert_to_intc(frmbrwstype)
    i_xpos = library.convert_to_FL_Coord(xpos)
    i_ypos = library.convert_to_FL_Coord(ypos)
    i_width = library.convert_to_FL_Coord(width)
    i_height = library.convert_to_FL_Coord(height)
    s_label = library.convert_to_bytestrc(label)
    library.keep_elem_refs(frmbrwstype, xpos, ypos, width, height, label, \
            i_frmbrwstype, i_xpos, i_ypos, i_width, i_height, s_label)
    retval = _fl_add_formbrowser(i_frmbrwstype, i_xpos, i_ypos, i_width, \
            i_height, s_label)
    return retval


# fl_create_formbrowser function placeholder (internal)


def fl_get_formbrowser_numforms(ptr_flobject):
    """fl_get_formbrowser_numforms(ptr_flobject) -> numforms

    Finds out the total number of forms in a formbrowser flobject.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject

    Returns
    -------
        numforms : int
            number of forms in formbrowser

    Examples
    --------
        >>> frmsnum = fl_get_formbrowser_numforms(pfrmbrobj)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_get_formbrowser_numforms = library.cfuncproto(
        library.load_so_libforms(), "fl_get_formbrowser_numforms",
        cty.c_int, [cty.POINTER(xfdata.FL_OBJECT)],
        """int fl_get_formbrowser_numforms(FL_OBJECT * ob)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    library.keep_elem_refs(ptr_flobject)
    retval = _fl_get_formbrowser_numforms(ptr_flobject)
    return retval


def fl_get_formbrowser_form(ptr_flobject, seqnum):
    """fl_get_formbrowser_form(ptr_flobject, seqnum) -> ptr_flform

    Finds out the form handle from the sequence number.

    Parameters
    ----------
        ptr_flobject : pointer to xfdata.FL_OBJECT
            formbrowser flobject
        seqnum : int
            sequence number of the form

    Returns
    -------
        ptr_flform : pointer to xfdata.FL_FORM
            form

    Examples
    --------
        >>> pform = fl_get_formbrowser_form(pfrmbrobj, 2)

    Notes
    -----
        Status: NA-UTest + Doc + NoDemo = Maybe

    """
    _fl_get_formbrowser_form = library.cfuncproto(
        library.load_so_libforms(), "fl_get_formbrowser_form",
        cty.POINTER(xfdata.FL_FORM), [cty.POINTER(xfdata.FL_OBJECT),
        cty.c_int],
        """FL_FORM * fl_get_formbrowser_form(FL_OBJECT * ob, int n)""")
    library.check_if_flinitialized()
    library.verify_flobjectptr_type(ptr_flobject)
    i_seqnum = library.convert_to_intc(seqnum)
    library.keep_elem_refs(ptr_flobject, seqnum, i_seqnum)
    retval = _fl_get_formbrowser_form(ptr_flobject, i_seqnum)
    return retval

