skin.h

libminigui-1.3.0.tar.gz。 miniGUI的库函数源代码！

 *      <name of skin1> {
 *          items {
 *              <id of item1> {
 *                  style: 
 *                  x:
 *                  y:
 *                  test_rect:
 *                  bmp_id:
 *                  tip:
 *                  type_data {
 *                      ...
 *                  }
 *              }
 *              <id of item2> {
 *                  style: 
 *                  x:
 *                  y:
 *                  test_rect:
 *                  bmp_id:
 *                  tip:
 *                  type_data {
 *                      ...
 *                  }
 *              }
 *              ...
 *          }
 *      }
 *      <name of skin2> {
 *          items {
 *              ...
 *          }
 *      }
 *      <name of skin3> {
 *          items {
 *              ...
 *          }
 *      }
 *  }
 * }
 *
 * \endcode
 *
 * 
 * \return This function returns the pointer to the skin set
 *         when success, otherwise NULL.
 *
 * \sa general_rw_fns, skin_set_unload, skin_init
 */
skin_set_t* skin_set_load (MG_RWops* skin_info);

/**
 * \fn void skin_set_unload (skin_set_t* skin_set)
 * \brief Unloads a skin set.
 *
 * This function unloads the skin set \a skin_set. It destroies
 * the bitmap objects, the logical fonts, and the skin objects.
 *
 * \sa skin_set_load, skin_destroy
 */
void skin_set_unload (skin_set_t* skin_set);

/**
 * \fn skin_head_t* skin_set_find_skin (skin_set_t* skin_set, const char* skin_name)
 * \brief Finds a skin object in a skin set.
 *
 * This function finds a skin object which matches the name \a skin_name in a skin set.
 *
 * \sa skin_set_load
 */
skin_head_t* skin_set_find_skin (skin_set_t* skin_set, const char* skin_name);

/**
 * \fn BOOL skin_init (skin_head_t* skin, skin_event_cb_t event_cb, skin_msg_cb_t msg_cb)
 * \brief Initializes a skin.
 *
 * This function initializes a skin \a skin before it can be used.
 * The initialization of a skin includes skin items initialization, etc, 
 * such as creating the hit-test region, allocating space for label, and so on.
 *
 * \param skin The pointer to the skin object. The skin can be
 *        a object returned by \a skin_set_find_skin or a hard-coded
 *        skin_head_t structure.
 * \param event_cb The item event callback of the skin.
 * \param msg_cb The window message callback of the skin window.
 *
 * \return TRUE for success, otherwise FALSE.
 *
 * \sa skin_set_load, skin_destroy, skin_set_find_skin
 */
BOOL skin_init (skin_head_t* skin, skin_event_cb_t event_cb, skin_msg_cb_t msg_cb);

/**
 * \fn void skin_deinit (skin_head_t* skin)
 * \brief Deinitializes an initialized skin.
 *
 * This function deinitializes a skin, opposed to skin_init.
 *
 * \param skin The pointer to the skin object.
 *
 * \sa skin_set_load, skin_init
 */
void skin_deinit (skin_head_t* skin);

/**
 * \fn HWND create_skin_main_window (skin_head_t* skin, HWND hosting, int x, int y, int w, int h, BOOL modal)
 * \brief Creates a main window for a skin.
 *
 * This function creates a main window for the skin pointed to by \a skin.
 * The main window will have no caption, no menu, and no frame. However,
 * the window's caption string will be the name of the skin object.
 *
 * \param skin The pointer to the initialized skin object.
 * \param hosting The the hosting main window.
 * \param x X-coordinate of the expected main window.
 * \param y Y-coordinate of the expected main window.
 * \param w The width of the expected main window.
 * \param h The height of the expected main window.
 * \param modal Whether to be a modal or modeless main window.
 *
 * \return The handle to the main window.
 *
 * \note The skin will store itself as the main window's additional data,
 *       so application should not call SetWindowAdditionalData to store
 *       other value.
 *
 * \sa skin_set_load, create_skin_control
 */
HWND create_skin_main_window (skin_head_t* skin, HWND hosting, int x, int y, int w, int h, BOOL modal);

/**
 * \fn HWND create_skin_control (skin_head_t* skin, HWND parent, int id, int x, int y, int w, int h)
 * \brief Creates a control for a skin.
 *
 * This function creates a control for the skin pointed to by \a skin.
 *
 * \param skin The pointer to the initialized skin object.
 * \param parent The handle to the parent window of the expected control.
 * \param id The identifier of the expected control.
 * \param x X-coordinate of the expected control in the parent window's client area.
 * \param y Y-coordinate of the expected control in the parent window's client area.
 * \param w The width of the expected control.
 * \param h The height of the expected control.
 *
 * \return The handle to the control.
 *
 * \note The skin will store itself as the control's additional data,
 *       so application should not call SetWindowAdditionalData to store other value.
 *
 *       You can also create a skin control by calling CreateWindowEx in the following manner:
 * \code
 *     CreateWindowEx (CTRL_SKIN, "", WS_VISIBLE | WS_CHILD, WS_EX_NONE, id, x, y, w, h, parent, (DWORD) skin);
 * \endcode
 *
 * \sa skin_set_load, create_skin_main_window
 */
HWND create_skin_control (skin_head_t* skin, HWND parent, int id, int x, int y, int w, int h);

/**
 * \fn void destroy_skin_window (HWND hwnd)
 * \brief Destroies a skin window.
 *
 * The function destroies the skin main window or control.
 *  
 * \param hwnd The handle to the skin window.
 *
 * \sa create_skin_main_window, create_skin_control
 */
void destroy_skin_window (HWND hwnd);

/**
 * \fn skin_head_t* set_window_skin (HWND hwnd, skin_head_t *new_skin)
 * \brief Sets new skin.
 *
 * The function sets a new skin pointed to by \a new_skin for
 * the skin window \a hwnd.
 *
 * \param hwnd The handle to the skin window.
 * \param new_skin The pointer to the new skin object.
 *
 * \return The pointer to the old skin object.
 *
 * \sa skin_set_event_cb, skin_set_msg_cb
 */
skin_head_t* set_window_skin (HWND hwnd, skin_head_t *new_skin);

/**
 * \fn skin_head_t* get_window_skin (HWND hwnd)
 * \brief Gets new skin.
 *
 * The function gets the skin of skin window \a hwnd.
 *
 * \param hwnd The handle to the skin window.
 *
 * \return The pointer to the skin object.
 *
 * \sa skin_set_event_cb, skin_set_msg_cb
 */
skin_head_t* get_window_skin (HWND hwnd);

/**
 * \fn skin_event_cb_t skin_set_event_cb (skin_head_t* skin, skin_event_cb_t event_cb)
 * \brief Sets new event callback of a skin.
 *
 * This function sets \a event_cb as the event callback of the skin \a skin.
 *
 * \param skin The pointer to the skin object.
 * \param event_cb The new event callback.
 *
 * \return The old event callback.
 *
 * \sa skin_set_msg_cb
 */
static inline skin_event_cb_t skin_set_event_cb (skin_head_t* skin, skin_event_cb_t event_cb)
{
    skin_event_cb_t old = skin->event_cb;
    skin->event_cb = event_cb;
    return old;
}

/**
 * \fn skin_msg_cb_t skin_set_msg_cb (skin_head_t* skin, skin_msg_cb_t msg_cb)
 * \brief Sets new message callback of a skin window.
 *
 * This function sets \a msg_cb as the message callback of the skin \a skin.
 *
 * \param skin The pointer to the skin object.
 * \param msg_cb The new message callback.
 *
 * \return The old message callback.
 *
 * \sa skin_set_event_cb
 */
static inline skin_msg_cb_t skin_set_msg_cb (skin_head_t* skin, skin_msg_cb_t msg_cb)
{
    skin_msg_cb_t old = skin->msg_cb;
    skin->msg_cb = msg_cb;
    return old;
}

/**
 * \fn skin_item_t* skin_get_item (skin_head_t* skin, int id)
 * \brief Retrives a skin item through its identifier.
 *
 * This function retrives the pointer to a skin item by its identifier.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 *
 * \return The pointer to the skin item, NULL when error.
 *
 * \sa skin_item_s
 */
skin_item_t* skin_get_item (skin_head_t* skin, int id);

/**
 * \fn DWORD skin_get_item_status (skin_head_t* skin, int id)
 * \brief Retrives the common status of a skin item.
 *
 * This function retrives the common status of a skin item by its identifier.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 *
 * \return The common status of the skin items, zero when error.
 *
 * \sa skin_item_s, skin_show_item, skin_enable_item, skin_set_hilited_item
 */
DWORD skin_get_item_status (skin_head_t* skin, int id);

/**
 * \fn skin_item_t* skin_get_hilited_item (skin_head_t* skin)
 * \brief Gets the current highlighted skin item.
 *
 * \param skin The pointer to the skin.
 *
 * \return The pointer to the current highlighted skin item.
 *
 * \sa skin_item_s, skin_set_hilited_item
 */
skin_item_t* skin_get_hilited_item (skin_head_t* skin);

/**
 * \fn DWORD skin_show_item (skin_head_t* skin, int id, BOOL show)
 * \brief Showes or hides a skin item.
 *
 * This function showes or hides a skin item whose identifier is \a id.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 * \param show TRUE for show, FALSE for hide.
 *
 * \return The current common status of the skin items, zero when error.
 *
 * \sa skin_item_s, skin_get_item_status
 */
DWORD skin_show_item (skin_head_t* skin, int id, BOOL show);

/**
 * \fn BOOL skin_enable_item (skin_head_t* skin, int id, BOOL enable)
 * \brief Enables or disables a skin item.
 *
 * This function enables or disables a skin item whose identifier is \a id.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 * \param enable TRUE for enable, FALSE for disable.
 *
 * \return The current common status of the skin items, zero when error.
 *
 * \sa skin_set_load
 */
DWORD skin_enable_item (skin_head_t* skin, int id, BOOL enable);

/**
 * \fn skin_item_t* skin_set_hilited_item (skin_head_t* skin, int id)
 * \brief Sets the current highlighted skin item.
 *
 * This function sets the current highlighted skin item.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 *
 * \return The pointer to the old highlighted skin item.
 *
 * \sa skin_item_s, skin_get_hilited_item
 */
skin_item_t* skin_set_hilited_item (skin_head_t* skin, int id);

/**
 * \fn BOOL skin_get_check_status (skin_head_t* skin, int id)
 * \brief Gets the check status of a check button item.
 *
 * This function gets the check status of a check button item,
 * checked or unchecked.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 *
 * \return TRUE for checked, FALSE for unchecked.
 *
 * \sa skin_item_s, skin_set_check_status
 */
BOOL skin_get_check_status (skin_head_t* skin, int id);

/**
 * \fn DWORD skin_set_check_status (skin_head_t* skin, int id, BOOL check)
 * \brief Sets the check status of a check button item.
 *
 * This function sets the check status of a check button item.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 * \param check Checks it or not.
 *
 * \return The current common status of the check button item.
 *
 * \sa skin_item_s, skin_get_check_status
 */
DWORD skin_set_check_status (skin_head_t* skin, int id, BOOL check);

/**
 * \fn const char* skin_get_item_label (skin_head_t* skin, int id)
 * \brief Gets the label string of a label item.
 *
 * This function returns the label string of a label item whose
 * identifier is \a id.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 *
 * \return The pointer to the label string. You should not
 *         modify the content of the string directly.
 *
 * \sa skin_item_s, skin_set_item_label
 */
const char* skin_get_item_label (skin_head_t* skin, int id);

/**
 * \fn BOOL skin_set_item_label (skin_head_t* skin, int id, const char* label)
 * \brief Sets the label string of a label item.
 *
 * This function sets the label string of a label item and reflects
 * the appearance of the item if it is visible.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 * \param label The pointer to the new label string.
 *
 * \return TRUE for success, FALSE on error.
 *
 * \sa skin_item_s, skin_get_item_label
 */
BOOL skin_set_item_label (skin_head_t* skin, int id, const char* label);

/**
 * \fn HWND skin_get_control_hwnd (skin_head_t* skin, int id)
 * \brief Gets the handle to a skin control item in the skin.
 *
 * This function returns the handle to a skin control item whose
 * identifier is \a id.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin control item.
 *
 * \return The handle to the control.
 *
 * \sa skin_item_s
 */
HWND skin_get_control_hwnd (skin_head_t* skin, int id);

/**
 * \fn int skin_get_thumb_pos (skin_head_t* skin, int id)
 * \brief Gets the thumb position of a slider item.
 *
 * This function gets the thumb position of a slider item.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 *
 * \return The current thumb position.
 *
 * \sa skin_item_s, skin_set_thumb_pos
 */
int skin_get_thumb_pos (skin_head_t* skin, int id);

/**
 * \fn BOOL skin_set_thumb_pos (skin_head_t* skin, int id, int pos)
 * \brief Sets the thumb position of a slider item.
 *
 * This function sets the thumb position of a slider item whose identifier
 * is \a id to the value of \a pos. It will redraw the item if the position
 * changed.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 * \param pos The new position value.
 *
 * \return TRUE for success, FALSE on error.
 *
 * \sa skin_item_s, skin_get_thumb_pos
 */
BOOL skin_set_thumb_pos (skin_head_t* skin, int id, int pos);

/**
 * \fn BOOL skin_get_slider_info (skin_head_t* skin, int id, sie_slider_t* sie)
 * \brief Retrives the sliding information of a slider item.
 *
 * This function retrives the sliding information of a slider item whose
 * identifier is \a id.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 * \param sie The pointer to a buffer which will be used to return the
 *        sliding information.
 *
 * \return TRUE for success, FALSE on error.
 *
 * \sa skin_item_s, skin_set_slider_info
 */
BOOL skin_get_slider_info (skin_head_t* skin, int id, sie_slider_t* sie);

/**
 * \fn BOOL skin_set_slider_info (skin_head_t* skin, int id, const sie_slider_t* sie)
 * \brief Sets the sliding information of a slider item.
 *
 * This function sets the sliding information of a slider item whose
 * identifier is \a id.
 *
 * \param skin The pointer to the skin.
 * \param id The identifier of the skin item.
 * \param sie The pointer to a sliding information structure.
 *
 * \return TRUE for success, FALSE on error.
 *
 * \sa skin_set_load
 */
BOOL skin_set_slider_info (skin_head_t* skin, int id, const sie_slider_t* sie);

/**
 * \fn int skin_scale_slider_pos (const sie_slider_t* org, int new_min, int new_max)
 * \brief Scales the sliding position.
 *
 * This function is a helper function, it calculates and returns 
 * the new position value of a sliding information in the new sliding range
 * defined by \a new_max and \a new_min.
 * 
 * \param org The original sliding information, its range and current position value.
 * \param new_min The new minimal value.
 * \param new_max The new maximal value.
 *
 * \return The new position value.
 *
 * \sa sie_slider_t
 */
int skin_scale_slider_pos (const sie_slider_t* org, int new_min, int new_max);


#ifdef __cplusplus
}
#endif  /* __cplusplus */

    /** @} end of mgext_skin_fns */

    /** @} end of mgext_fns */

#endif /* _EXT_SKIN */

#endif /* _MGUI_SKIN_H */