diff options
author | mvglasow <michael@vonglasow.com> | 2015-11-07 18:43:14 +0100 |
---|---|---|
committer | mvglasow <michael@vonglasow.com> | 2015-11-07 18:43:14 +0100 |
commit | 26788fb75cac1b51371e54cedebdbfa6887b597a (patch) | |
tree | 6ccf66772ad4449215f2193bead1911f5c672aff | |
parent | 3ce0f5b4410d98c2f08e7288dcb1c209e3cecdf9 (diff) | |
parent | b4ed6be6a0fd9749972d055a7f6395f6d5385b89 (diff) | |
download | navit-26788fb75cac1b51371e54cedebdbfa6887b597a.tar.gz |
Merge pull request #34 from mvglasow/docR6330
Refactor:core:More documentation
-rw-r--r-- | navit/navit.c | 40 | ||||
-rw-r--r-- | navit/xmlconfig.c | 25 |
2 files changed, 64 insertions, 1 deletions
diff --git a/navit/navit.c b/navit/navit.c index 5420a08cc..2fe37c384 100644 --- a/navit/navit.c +++ b/navit/navit.c @@ -151,7 +151,10 @@ struct navit { struct log *textfile_debug_log; struct pcoord destination; int destination_valid; - int blocked; + int blocked; /**< Whether draw operations are currently blocked. This can be a combination of the + following flags: + 1: draw operations are blocked + 2: draw operations are pending, requiring a redraw once draw operations are unblocked */ int w,h; int drag_bitmap; int use_mousewheel; @@ -381,6 +384,20 @@ navit_popup(void *data) } +/** + * @brief Sets a flag indicating that the current button event should be ignored by subsequent handlers. + * + * Calling this function will set the {@code ignore_button} member to {@code true} and return its previous state. + * The default handler, {@link navit_handle_button(navit *, int, int, point *, callback *)} calls this function + * just before the actual event handling core and aborts if the result is {@code true}. In order to prevent + * multiple handlers from firing on a single event, custom button click handlers should implement the same logic + * for events they wish to handle. + * + * If a handler wishes to pass down an event to other handlers, it must abort without calling this function. + * + * @param this_ The navit instance + * @return {@code true} if the caller should ignore the button event, {@code false} if it should handle it + */ int navit_ignore_button(struct navit *this_) { @@ -3449,6 +3466,24 @@ navit_disable_suspend() { callback_list_call_attr_0(global_navit->attr_cbl,attr_unsuspend); } +/** + * @brief Blocks or unblocks redraw operations. + * + * The {@code block} parameter specifies the operation to carry out: + * + * {@code block > 0} cancels all draw operations in progress and blocks future operations. It sets flag 1 of the + * {@code blocked} member. If draw operations in progress were canceled, flag 2 is also set. + * + * {@code block = 0} unblocks redraw operations, resetting {@code blocked} to 0. If flag 2 was previously set, + * indicating that draw operations had been previously canceled, a redraw is triggered. + * + * {@code block < 0} unblocks redraw operations and forces a redraw. As above, {@code blocked} is reset to 0. + * + * @param this_ The navit instance + * @param block The operation to perform, see description + * + * @return {@code true} if a redraw operation was triggered, {@code false} if not + */ int navit_block(struct navit *this_, int block) { @@ -3467,6 +3502,9 @@ navit_block(struct navit *this_, int block) return 0; } +/** + * @brief Returns whether redraw operations are currently blocked. + */ int navit_get_blocked(struct navit *this_) { return this_->blocked; diff --git a/navit/xmlconfig.c b/navit/xmlconfig.c index 66b73fd02..f752998eb 100644 --- a/navit/xmlconfig.c +++ b/navit/xmlconfig.c @@ -1295,6 +1295,31 @@ navit_object_attr_iter_destroy(struct attr_iter *iter) g_free(iter); } +/** + * @brief Generic get function + * + * This function searches an attribute list for an attribute of a given type and stores it in the {@code attr} + * parameter. Internally it calls + * {@link attr_generic_get_attr(struct attr **, struct attr **, enum attr_type, struct attr *, struct attr_iter *)} + * to retrieve the attribute; see its documentation for details. + * <p> + * Searching for attr_any or attr_any_xml is supported. + * <p> + * An iterator can be specified to get multiple attributes of the same type: + * The first call will return the first match; each subsequent call + * with the same iterator will return the next match. If no more matching + * attributes are found in either of them, false is returned. + * + * @param obj The object to return an attribute for. This can be any Navit object type, but the parameter should + * be cast to {@code struct navit_object *} to avoid compiler warnings. + * @param type The attribute type to search for. Searching for {@code attr_any} or {@code attr_any_xml} is + * possible. + * @param attr Points to a {@code struct attr} which will receive the attribute + * @param iter An iterator to receive multiple attributes of the same type with subsequent calls. If {@code NULL}, + * the first matching attribute will be retrieved. + * + * @return True if a matching attribute was found, false if not. + */ int navit_object_get_attr(struct navit_object *obj, enum attr_type type, struct attr *attr, struct attr_iter *iter) { |