This is an automated email from the git hooks/post-receive script.
git pushed a commit to branch edje-vector-intergration
in repository efl.
View the commit online.
commit 392e7c8220c7a8aba3d627f43ca5d7495199d332
Author: [email protected] <[email protected]>
AuthorDate: Thu Apr 30 20:08:31 2026 -0600
docs: introduce vector state animation tutorial and Edje_Edit API reference (Phase 8.4)
Phase 8.4 closes the Edje vector state animation feature series by providing
user-facing documentation and comprehensive Doxygen API reference for theme
authors and visual-editor implementers.
Three components:
1. New doc/edje_vector_states.dox tutorial page (@page tutorial_edje_vector_states):
- Introduction: motivation and capabilities (named trees, per-state overrides,
live transitions)
- Why use it: designer-friendly, resolution-independent, class-aware retinting,
zero-copy transitions
- Feature specification pointer to spec v2
- EDC walkthrough: color_classes setup, named vector tree, VECTOR part
definition with state descriptions, programs for signal-to-state binding
- Minimal C harness walkthrough from src/examples/edje/edje-vector-states.c
- Programmatic editing via Edje_Edit API: describes all 10 Vector Tree API
symbols and their use cases
- Compile-time diagnostics (Phase 7): canonical reference for VEC001-VEC014
codes with default severity and -W escalation/demotion examples
- Three TODO(spec-rev3) comments documenting known deviations from v2 spec:
* stroke{}/fill{} block form not implemented (dotted syntax only)
* vector.shape "name" {} inline form not implemented (target: statement)
* VEC014 hard error vs spec's last-write-wins policy
2. Updated doc/Doxyfile.in:
- Added edje_vector_states.dox to the INPUT list after edje_examples.dox
so the tutorial is built into generated documentation
3. Comprehensive Edje_Edit.h Doxygen rewrite (+197 -73):
- All 10 Vector Tree API functions now have full documentation:
edje_edit_vg_trees_list_get, edje_edit_vg_tree_exists, edje_edit_vg_tree_add,
edje_edit_vg_tree_del, edje_edit_part_vector_tree_use_get/set,
edje_edit_part_vector_overrides_list_get, edje_edit_part_vector_override_add/del,
edje_edit_vector_node_color_class_get/set
- Each function now has: @brief (1-liner), exhaustive @param documenting
NULL-safety constraints, comprehensive @return covering success and all
failure modes, @since 1.27, and @see cross-references
- Group @name expanded to distinguish Vector Tree API from SVG-file image
directory API with explicit pointer to tutorial
- All examples use proper function call syntax with () suffix for consistency
This closes the documentation gap left after Phases 1-8.3. Theme authors and
visual-editor implementations now have a tutorial entry point, complete API
reference, and diagnostic troubleshooting guide.
Build verified: ninja -C build (no work), edje_suite: 91/91 pass (no regressions).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---
doc/Doxyfile.in | 1 +
doc/edje_vector_states.dox | 240 ++++++++++++++++++++++++++++++++++++++++
src/lib/edje/Edje_Edit.h | 270 +++++++++++++++++++++++++++++++++------------
3 files changed, 438 insertions(+), 73 deletions(-)
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 5b0711a390..9ff7434104 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -608,6 +608,7 @@ INPUT = @top_srcdir@/src/lib \
@srcdir@/eldbus_examples.dox \
@srcdir@/ephysics_examples.dox \
@srcdir@/edje_examples.dox \
+ @srcdir@/edje_vector_states.dox \
@top_srcdir@/src/bin/edje/edje_cc_handlers.c \
@srcdir@/emotion_examples.dox \
@srcdir@/elementary_examples.dox
diff --git a/doc/edje_vector_states.dox b/doc/edje_vector_states.dox
new file mode 100644
index 0000000000..75c9910bd2
--- /dev/null
+++ b/doc/edje_vector_states.dox
@@ -0,0 +1,240 @@
+/**
+ * @page tutorial_edje_vector_states Edje Vector State Animation
+ *
+ * @section edje_vg_intro Introduction
+ *
+ * Edje vector state animation lets a theme author embed resolution-independent
+ * SVG-style vector content directly in an EDC file and morph that content
+ * smoothly between named states — without swapping bitmap frames, loading
+ * external image files, or writing a single line of C.
+ *
+ * Three capabilities combine to make this work:
+ *
+ * -# @b Named @b vector @b trees. A shared @c vectors {} block at the top of
+ * the EDC file defines one or more named trees of vector nodes (shapes,
+ * gradients, containers). Each tree is stored in the compiled @c .edj and
+ * can be referenced by any number of VECTOR parts.
+ * -# @b Per-state @b overrides. Each state description of a VECTOR part can
+ * include a @c vector.shape {} block that selects a named node inside the
+ * active tree and replaces individual properties (path geometry, fill /
+ * stroke colour or colour-class binding, stroke width, transform) for that
+ * state only. Unmentioned properties keep the base-tree value.
+ * -# @b Live @b transitions. When Edje interpolates between two states it
+ * linearly blends the overridden values. Path geometry is morphed vertex-
+ * by-vertex (topologies must match — same command sequence), colour
+ * components are blended channel-by-channel, and scalar values such as
+ * stroke width are lerped as floats. The result drives Efl_VG directly so
+ * the GPU renders a smooth animated curve without any intermediate bitmaps.
+ *
+ * @section edje_vg_why Why use it?
+ *
+ * @li @b Designer-friendly: the entire visual appearance lives in the EDC file.
+ * No C code is needed to change shapes or colours on hover / focus / press.
+ * @li @b Resolution-independent: vector content scales to any DPI without
+ * artefacts.
+ * @li @b Class-aware retinting: bind a shape's fill or stroke to a
+ * @c color_class so the host application can retint the widget at runtime
+ * with @c edje_object_color_class_set() — the same mechanism used for text
+ * and image parts.
+ * @li @b Zero-copy transitions: the materializer works directly on the
+ * interpolated property snapshot; no extra pixmap allocation is needed.
+ *
+ * @section edje_vg_spec Feature specification
+ *
+ * The full design document is at @c edje-vector-state-animation-spec-v2.md in
+ * the repository root. Section §11 of the spec contains the canonical example
+ * that this tutorial reproduces verbatim.
+ *
+ * @section edje_vg_edc EDC walkthrough
+ *
+ * The worked example ships at
+ * @c src/examples/edje/vector_states.edc. The discussion below follows
+ * that file section by section.
+ *
+ * @subsection edje_vg_edc_colorclasses Color classes
+ *
+ * @code
+ * color_classes {
+ * color_class { name: "logo_fill"; color: 80 140 255 255; }
+ * color_class { name: "logo_hover"; color: 255 200 80 255; }
+ * color_class { name: "logo_outline"; color: 20 20 20 255; }
+ * }
+ * @endcode
+ *
+ * Three colour classes are declared. @c logo_fill is the default fill for the
+ * shape; @c logo_hover replaces it in the hovered state. Because these are
+ * colour classes, the host application can override either at runtime with
+ * @c edje_object_color_class_set() without touching the theme binary.
+ *
+ * @subsection edje_vg_edc_tree Named vector tree
+ *
+ * @code
+ * vectors {
+ * vector { name: "logo_glyph";
+ * viewbox: 0 0 100 100;
+ * shape { name: "body";
+ * path: "M0,0 L0,0 L100,0 L100,0 L100,100 L100,100 L0,100 L0,100 L0,0";
+ * fill.color_class: "logo_fill";
+ * stroke.color_class: "logo_outline";
+ * stroke.width: 2;
+ * }
+ * }
+ * }
+ * @endcode
+ *
+ * The @c vectors {} block defines the named tree @c "logo_glyph". It contains
+ * one shape node named @c "body" whose path is a closed square. The shape uses
+ * colour-class bindings for both fill and stroke so the colours are themeable
+ * without recompilation.
+ *
+ * The path string uses SVG path syntax: @c M (move-to), @c L (line-to), @c Z
+ * (close). The command sequence — @c M + 8×L + Z — must be the same in every
+ * state description that overrides this shape, because path morphing works
+ * vertex-by-vertex.
+ *
+ * @subsection edje_vg_edc_part VECTOR part and state descriptions
+ *
+ * @code
+ * part { name: "logo"; type: VECTOR;
+ * description { state: "default" 0.0;
+ * rel1.relative: 0.0 0.0;
+ * rel2.relative: 1.0 1.0;
+ * vector.use: "logo_glyph";
+ * }
+ * description { state: "hover" 0.0;
+ * inherit: "default" 0.0;
+ * vector.shape {
+ * target: "body";
+ * path: "M0,0 L50,-80 L100,0 L180,50 L100,100 L50,180 L0,100 L-80,50 L0,0";
+ * fill.color_class: "logo_hover";
+ * stroke.width: 4;
+ * }
+ * }
+ * }
+ * @endcode
+ *
+ * The @c default description binds the part to the @c "logo_glyph" tree via
+ * @c vector.use. The @c hover description inherits everything from @c default
+ * and adds a @c vector.shape {} override block:
+ *
+ * -# @c target: names the shape node being overridden (@c "body").
+ * -# @c path: provides an alternative star path. It has the same command
+ * sequence (M + 8×L + Z) so Edje can morph it smoothly.
+ * -# @c fill.color_class: swaps the fill to @c "logo_hover" in this state.
+ * -# @c stroke.width: widens the outline from 2 to 4.
+ *
+ * Properties not mentioned in the override (@c stroke.color_class) retain
+ * their base-tree value.
+ *
+ * @subsection edje_vg_edc_programs Programs
+ *
+ * @code
+ * programs {
+ * program { signal: "mouse,in"; source: "logo";
+ * action: STATE_SET "hover" 0.0;
+ * target: "logo";
+ * transition: SINUSOIDAL 0.3;
+ * }
+ * program { signal: "mouse,out"; source: "logo";
+ * action: STATE_SET "default" 0.0;
+ * target: "logo";
+ * transition: SINUSOIDAL 0.3;
+ * }
+ * }
+ * @endcode
+ *
+ * Two programs wire mouse-in / mouse-out signals to a 300 ms sinusoidal
+ * transition. No C code is needed; the runtime materializer blends the path
+ * vertices and scalar properties automatically.
+ *
+ * @section edje_vg_c C harness
+ *
+ * The minimal C harness at @c src/examples/edje/edje-vector-states.c loads the
+ * compiled @c vector_states.edj, displays the @c "ui/logo" group in a 400×400
+ * window, and registers signal callbacks so the terminal shows which transition
+ * is occurring. The core is:
+ *
+ * @code
+ * edje_obj = edje_object_add(evas);
+ * edje_object_file_set(edje_obj, edje_file, "ui/logo");
+ *
+ * edje_object_signal_callback_add(edje_obj, "mouse,in", "logo", _on_hover_in, NULL);
+ * edje_object_signal_callback_add(edje_obj, "mouse,out", "logo", _on_hover_out, NULL);
+ * @endcode
+ *
+ * Runtime retinting is straightforward:
+ *
+ * @code
+ * // Change the fill colour without recompiling the theme:
+ * edje_object_color_class_set(edje_obj, "logo_fill",
+ * 255, 80, 80, 255, // object colour
+ * 0, 0, 0, 0, // text colour (unused)
+ * 0, 0, 0, 0); // shadow colour (unused)
+ * @endcode
+ *
+ * To compile and run:
+ *
+ * @verbatim
+ * edje_cc src/examples/edje/vector_states.edc
+ * gcc -o edje-vector-states src/examples/edje/edje-vector-states.c \
+ * -DPACKAGE_DATA_DIR=\".\" \
+ * `pkg-config --cflags --libs evas ecore ecore-evas edje`
+ * ./edje-vector-states
+ * @endverbatim
+ *
+ * @section edje_vg_edit Programmatic editing via Edje_Edit
+ *
+ * Visual editors can inspect and modify vector trees at runtime using the
+ * Vector Tree API introduced in EFL 1.27. The key functions are:
+ *
+ * - edje_edit_vg_trees_list_get() — list all named trees in the file.
+ * - edje_edit_vg_tree_add() / edje_edit_vg_tree_del() — create or remove trees.
+ * - edje_edit_part_vector_tree_use_get() / edje_edit_part_vector_tree_use_set()
+ * — query or change which named tree a part-state is bound to.
+ * - edje_edit_part_vector_overrides_list_get() — enumerate override targets.
+ * - edje_edit_part_vector_override_add() / edje_edit_part_vector_override_del()
+ * — add or remove override entries on a part-state.
+ * - edje_edit_vector_node_color_class_get() / edje_edit_vector_node_color_class_set()
+ * — read or assign a colour-class binding to a specific node in a tree.
+ *
+ * All setters mark the Edje file dirty; call edje_edit_save() to persist the
+ * changes.
+ *
+ * @section edje_vg_diagnostics Compile-time diagnostics (Phase 7)
+ *
+ * @c edje_cc emits structured diagnostic messages for common authoring mistakes.
+ * Each code has a default severity (error, warning, or hint) that can be
+ * escalated or demoted on the command line:
+ *
+ * @verbatim
+ * edje_cc -W VEC001=error -W VEC012=hint my_theme.edc
+ * @endverbatim
+ *
+ * The diagnostic codes added in Phase 7 are:
+ *
+ * | Code | Default | Condition |
+ * |--------|----------|---------------------------------------------------------|
+ * | VEC001 | error | Duplicate node name within the same tree |
+ * | VEC003 | warning | Node name referenced by an override not found in tree |
+ * | VEC004 | error | Override path has different command topology than base |
+ * | VEC007 | warning | Gradient type changes between states (will not lerp) |
+ * | VEC009 | warning | Stop count changes between states (will not lerp) |
+ * | VEC010 | warning | Node type changes between states (will not lerp) |
+ * | VEC011 | error | fill.color_class and fill.color both set on same node |
+ * | VEC012 | error | stroke.color_class and stroke.color both set on node |
+ * | VEC014 | error | Both matrix and decomposed transform forms on same node |
+ *
+ * @note
+ * The following departures from the v2 spec are intentional for this release:
+ *
+ * @c TODO(spec-rev3): stroke{} / fill{} block form (§5.2) not implemented —
+ * only the flat dotted syntax (@c fill.color_class:, @c stroke.width:, etc.)
+ * is accepted. Block form is scheduled for a follow-up.
+ *
+ * @c TODO(spec-rev3): @c vector.shape "name" {} inline-name form (§4.3) not
+ * implemented — use the @c target: statement inside @c vector.shape {} instead.
+ *
+ * @c TODO(spec-rev3): VEC014 is a hard compile error here; the v2 spec
+ * described last-write-wins semantics. The hard-error policy was adopted in
+ * Phase 7.3 to surface latent authoring bugs early.
+ */
diff --git a/src/lib/edje/Edje_Edit.h b/src/lib/edje/Edje_Edit.h
index 90811611aa..5a1b2fb3c7 100644
--- a/src/lib/edje/Edje_Edit.h
+++ b/src/lib/edje/Edje_Edit.h
@@ -8953,167 +8953,291 @@ EAPI extern Eina_Error EDJE_EDIT_ERROR_GROUP_DOES_NOT_EXIST;
/******************************************************************************/
/**
* @name Vector Tree API
- * Functions for manipulating the named Edje_Vg_Tree directory (Phase 8.2).
- * This API operates on the toplevel @c vectors {} block, which holds named
- * Edje_Vg_Tree entries. It is distinct from the SVG-file image-directory
- * API (edje_edit_vector_del, edje_edit_vectors_list_get, etc.).
+ * Functions for manipulating the named Edje_Vg_Tree directory.
+ *
+ * This API operates on the toplevel @c vectors {} block of an EDC file, which
+ * holds named Edje_Vg_Tree entries that VECTOR parts can reference with the
+ * @c vector.use: statement. It is entirely distinct from the SVG-file
+ * image-directory API (edje_edit_vector_del(), edje_edit_vectors_list_get(),
+ * etc.), which manages SVG asset files rather than in-line vector trees.
+ *
+ * Use edje_edit_save() after any setter to persist changes to disk.
+ *
+ * See also: @ref tutorial_edje_vector_states
*/ //@{
/**
- * @brief Returns the list of named vector-tree names in the file.
+ * @brief Returns the list of named vector-tree names stored in the file.
*
- * Use edje_edit_string_list_free() to release the returned list.
+ * Each element of the returned list is an Eina_Stringshare string. The list
+ * itself must be freed with edje_edit_string_list_free() when no longer needed;
+ * the individual strings are owned by the list and must not be freed separately.
*
- * @param obj Object being edited.
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ *
+ * @return A newly allocated @c Eina_List of @c Eina_Stringshare tree names on
+ * success, or @c NULL if the file contains no named trees or on error.
*
- * @return A list of Eina_Stringshare names, one per named Edje_Vg_Tree.
* @since 1.27
+ * @see edje_edit_vg_tree_exists()
+ * @see edje_edit_vg_tree_add()
+ * @see edje_edit_string_list_free()
*/
EAPI Eina_List *edje_edit_vg_trees_list_get(Evas_Object *obj);
/**
* @brief Tests whether a named vector tree exists in the file.
*
- * @param obj Object being edited.
- * @param name The tree name to look up.
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ * @param name The tree name to look up. Must not be @c NULL.
+ *
+ * @return @c EINA_TRUE if a tree with that name is present in the file's
+ * @c vectors {} directory, @c EINA_FALSE if it does not exist or
+ * if @p obj or @p name is @c NULL.
*
- * @return @c EINA_TRUE if a tree with that name is present, @c EINA_FALSE otherwise.
* @since 1.27
+ * @see edje_edit_vg_trees_list_get()
+ * @see edje_edit_vg_tree_add()
*/
EAPI Eina_Bool edje_edit_vg_tree_exists(Evas_Object *obj, const char *name);
/**
- * @brief Adds a new empty named vector tree to the file.
+ * @brief Adds a new, empty named vector tree to the file.
*
- * Returns @c EINA_FALSE if a tree with that name already exists.
+ * The new tree is empty (contains no nodes) after creation. Nodes must be
+ * populated via the @c edje_decc round-trip or by directly editing the EDC
+ * source. The file is marked dirty; call edje_edit_save() to persist.
*
- * @param obj Object being edited.
- * @param name The name for the new tree.
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ * @param name The name for the new tree. Must not be @c NULL. The name
+ * must be unique; the call fails if a tree with the same name
+ * already exists.
+ *
+ * @return @c EINA_TRUE on success, @c EINA_FALSE if a tree with @p name
+ * already exists, if either argument is @c NULL, or on allocation
+ * failure.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
* @since 1.27
+ * @see edje_edit_vg_tree_del()
+ * @see edje_edit_vg_tree_exists()
*/
EAPI Eina_Bool edje_edit_vg_tree_add(Evas_Object *obj, const char *name);
/**
* @brief Removes a named vector tree from the file.
*
- * Refuses and returns @c EINA_FALSE if any description's tree_id references
- * this tree (which would leave the file inconsistent).
+ * The call refuses to remove a tree that is referenced by at least one
+ * part-state @c vector.use: binding, returning @c EINA_FALSE in that case
+ * to avoid leaving the file in an inconsistent state. Use
+ * edje_edit_part_vector_tree_use_set() to clear all bindings first.
*
- * @param obj Object being edited.
- * @param name The name of the tree to remove.
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ * @param name The name of the tree to remove. Must not be @c NULL.
+ *
+ * @return @c EINA_TRUE on success, @c EINA_FALSE if the tree does not
+ * exist, is still referenced by a part-state, either argument is
+ * @c NULL, or an internal error occurs.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
* @since 1.27
+ * @see edje_edit_vg_tree_add()
+ * @see edje_edit_part_vector_tree_use_set()
*/
EAPI Eina_Bool edje_edit_vg_tree_del(Evas_Object *obj, const char *name);
/**
- * @brief Gets the named vector tree bound to the given part-state.
+ * @brief Gets the named vector tree bound to a given part-state.
*
- * The returned string is a newly added Eina_Stringshare; release with
- * edje_edit_string_free(). Returns NULL if no tree is bound (tree_id == -1)
- * or if the part is not of type VECTOR.
+ * Returns the name of the tree that the specified state will display when
+ * rendered, i.e., the argument that would appear after @c vector.use: in
+ * the EDC source.
*
- * @param obj Object being edited.
- * @param part Part name.
- * @param state State name (without value).
- * @param value State value.
+ * The returned string is a newly added Eina_Stringshare value. Release it
+ * with edje_edit_string_free() when done.
+ *
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ * @param part The name of the VECTOR part. Must not be @c NULL.
+ * @param state The state name, without the numeric value suffix (e.g.
+ * @c "default" rather than @c "default 0.0"). Must not be @c NULL.
+ * @param value The state value (typically @c 0.0).
+ *
+ * @return An Eina_Stringshare with the bound tree name on success; @c NULL
+ * if no tree is bound (the state has no @c vector.use: binding), if
+ * the part is not of type VECTOR, or if any argument is invalid.
*
- * @return The tree name or NULL.
* @since 1.27
+ * @see edje_edit_part_vector_tree_use_set()
+ * @see edje_edit_vg_trees_list_get()
+ * @see edje_edit_string_free()
*/
EAPI const char *edje_edit_part_vector_tree_use_get(Evas_Object *obj, const char *part, const char *state, double value);
/**
* @brief Binds a named vector tree to the given part-state.
*
- * Passing NULL for @p tree_name clears the binding (sets tree_id to -1).
+ * Sets the @c vector.use: binding for @p state on @p part so that the named
+ * tree is displayed when that state is active. Pass @c NULL for @p tree_name
+ * to clear an existing binding (equivalent to removing the @c vector.use:
+ * statement from the EDC source).
*
- * @param obj Object being edited.
- * @param part Part name.
- * @param state State name (without value).
- * @param value State value.
- * @param tree_name The tree to bind, or NULL to clear.
+ * The file is marked dirty; call edje_edit_save() to persist the change.
+ *
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ * @param part The name of the VECTOR part. Must not be @c NULL.
+ * @param state The state name, without the numeric value suffix.
+ * Must not be @c NULL.
+ * @param value The state value (typically @c 0.0).
+ * @param tree_name The name of an existing tree in the file's @c vectors {}
+ * directory, or @c NULL to clear the binding.
+ *
+ * @return @c EINA_TRUE on success, @c EINA_FALSE if @p part or @p state is
+ * @c NULL, if the part is not of type VECTOR, if @p tree_name is
+ * non-NULL but does not name an existing tree, or on internal error.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
* @since 1.27
+ * @see edje_edit_part_vector_tree_use_get()
+ * @see edje_edit_vg_tree_exists()
*/
EAPI Eina_Bool edje_edit_part_vector_tree_use_set(Evas_Object *obj, const char *part, const char *state, double value, const char *tree_name);
/**
- * @brief Returns the list of override target names for a part-state.
+ * @brief Returns the list of override target names active on a part-state.
*
- * Use edje_edit_string_list_free() to release the returned list.
+ * Each entry in the list is the name of a shape node in the base tree that
+ * the given state overrides with a @c vector.shape {} block. The list
+ * reflects the order in which overrides were added.
*
- * @param obj Object being edited.
- * @param part Part name.
- * @param state State name (without value).
- * @param value State value.
+ * Each element is an Eina_Stringshare string. Free the list with
+ * edje_edit_string_list_free() when no longer needed.
+ *
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ * @param part The name of the VECTOR part. Must not be @c NULL.
+ * @param state The state name, without the numeric value suffix.
+ * Must not be @c NULL.
+ * @param value The state value (typically @c 0.0).
+ *
+ * @return A newly allocated @c Eina_List of @c Eina_Stringshare target names
+ * on success, or @c NULL if there are no overrides, the part/state
+ * combination is invalid, or on error.
*
- * @return A list of Eina_Stringshare target names.
* @since 1.27
+ * @see edje_edit_part_vector_override_add()
+ * @see edje_edit_part_vector_override_del()
+ * @see edje_edit_string_list_free()
*/
EAPI Eina_List *edje_edit_part_vector_overrides_list_get(Evas_Object *obj, const char *part, const char *state, double value);
/**
- * @brief Adds an override entry for the given target node name.
+ * @brief Adds an override entry targeting the given node name to a part-state.
*
- * Returns @c EINA_FALSE if an override with that target already exists or on error.
+ * Creates an empty @c vector.shape {} override block for @p target on the
+ * specified part-state. After adding, use the per-property setter functions
+ * to populate the override's fields. The file is marked dirty; call
+ * edje_edit_save() to persist.
*
- * @param obj Object being edited.
- * @param part Part name.
- * @param state State name (without value).
- * @param value State value.
- * @param target Target node name.
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ * @param part The name of the VECTOR part. Must not be @c NULL.
+ * @param state The state name, without the numeric value suffix.
+ * Must not be @c NULL.
+ * @param value The state value (typically @c 0.0).
+ * @param target The name of the shape node in the base tree to override.
+ * Must not be @c NULL. The call fails if an override with
+ * the same target already exists on this state.
+ *
+ * @return @c EINA_TRUE on success, @c EINA_FALSE if an override for
+ * @p target already exists, if any pointer argument is @c NULL,
+ * if the part is not of type VECTOR, or on allocation failure.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
* @since 1.27
+ * @see edje_edit_part_vector_override_del()
+ * @see edje_edit_part_vector_overrides_list_get()
*/
EAPI Eina_Bool edje_edit_part_vector_override_add(Evas_Object *obj, const char *part, const char *state, double value, const char *target);
/**
- * @brief Removes the override entry for the given target node name.
+ * @brief Removes the override entry for the given target node from a part-state.
*
- * @param obj Object being edited.
- * @param part Part name.
- * @param state State name (without value).
- * @param value State value.
- * @param target Target node name.
+ * Deletes the @c vector.shape {} block that overrides @p target on the
+ * specified part-state. The file is marked dirty; call edje_edit_save()
+ * to persist.
+ *
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ * @param part The name of the VECTOR part. Must not be @c NULL.
+ * @param state The state name, without the numeric value suffix.
+ * Must not be @c NULL.
+ * @param value The state value (typically @c 0.0).
+ * @param target The name of the shape node whose override is to be removed.
+ * Must not be @c NULL.
+ *
+ * @return @c EINA_TRUE on success, @c EINA_FALSE if no override with that
+ * target exists on the state, if any pointer argument is @c NULL,
+ * if the part is not of type VECTOR, or on error.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
* @since 1.27
+ * @see edje_edit_part_vector_override_add()
+ * @see edje_edit_part_vector_overrides_list_get()
*/
EAPI Eina_Bool edje_edit_part_vector_override_del(Evas_Object *obj, const char *part, const char *state, double value, const char *target);
/**
- * @brief Gets the color-class binding on a node in a named toplevel tree.
+ * @brief Gets the color-class binding on a node within a named toplevel tree.
*
- * The returned string is a newly added Eina_Stringshare; release with
- * edje_edit_string_free().
+ * Returns the name of the color class bound to @p node in @p tree, i.e., the
+ * string that would appear after @c color_class: in the EDC source for that
+ * node. This is the binding on the base tree node; to inspect override-side
+ * bindings, query the state's override list.
*
- * @param obj Object being edited.
- * @param tree The named tree to look in.
- * @param node The node name within that tree.
+ * The returned string is a newly added Eina_Stringshare value. Release it
+ * with edje_edit_string_free() when done.
+ *
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ * @param tree The name of the toplevel vector tree. Must not be @c NULL.
+ * @param node The name of the node within that tree. Must not be @c NULL.
+ *
+ * @return An Eina_Stringshare with the color-class name on success; @c NULL
+ * if no class is bound to that node, if the tree or node does not
+ * exist, or if any argument is @c NULL.
*
- * @return The color-class name or NULL if none is set.
* @since 1.27
+ * @see edje_edit_vector_node_color_class_set()
+ * @see edje_edit_vg_trees_list_get()
+ * @see edje_edit_string_free()
*/
EAPI const char *edje_edit_vector_node_color_class_get(Evas_Object *obj, const char *tree, const char *node);
/**
- * @brief Sets the color-class binding on a node in a named toplevel tree.
+ * @brief Sets the color-class binding on a node within a named toplevel tree.
*
- * Passing NULL for @p class_name clears the binding.
+ * Associates @p class_name with @p node in @p tree so that the node's fill or
+ * stroke color can be overridden at runtime via edje_color_class_set() or
+ * edje_object_color_class_set(). Pass @c NULL for @p class_name to clear an
+ * existing binding.
*
- * @param obj Object being edited.
- * @param tree The named tree.
- * @param node The node name within that tree.
- * @param class_name The color class to bind, or NULL to clear.
+ * The file is marked dirty; call edje_edit_save() to persist the change.
+ *
+ * @param obj The Evas object representing the Edje file being edited.
+ * Must not be @c NULL.
+ * @param tree The name of the toplevel vector tree. Must not be @c NULL.
+ * @param node The name of the node within that tree. Must not be @c NULL.
+ * @param class_name The color-class name to bind, or @c NULL to clear the
+ * existing binding.
+ *
+ * @return @c EINA_TRUE on success, @c EINA_FALSE if the tree or node does not
+ * exist, if @p obj, @p tree, or @p node is @c NULL, or on allocation
+ * failure.
*
- * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
* @since 1.27
+ * @see edje_edit_vector_node_color_class_get()
+ * @see edje_color_class_set()
*/
EAPI Eina_Bool edje_edit_vector_node_color_class_set(Evas_Object *obj, const char *tree, const char *node, const char *class_name);
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
