path: root/doc/examples-js.dox

/**
 * @page Examples-js Examples with Javascript Bindings.
 *
 * Here is a list of Elementary JS Examples.
 *
 * @ref bg_js_example_02
 *
 * @ref calendar_js_example_01
 *
 * @ref calendar_js_example_03
 *
 * @ref clock_js_example
 *
 * @ref datetime_js_example
 *
 * @ref icon_js_example_01
 *
 * @ref separator_js_example_01
 *
 */

/**
 * @page bg_js_example_02 elm.Bg - Image background using Javascript Binding
 * @dontinclude bg_example_02.js

 * This is the second background example and shows how to use the
 * Elementary background object to set an image as background of your
 * application.

 * The first part consists of including the necessary modules and for
 * this we'll use the Node.js require() function. In this example, we
 * are working solely with elm module.

 * @skipline require
 
 * Next step is creating an Elementary window with Win_Standard
 * without a parent, which is the type used for all of our
 * examples. Here we also set the title that will appear at the top of
 * our window and then the autohide state for it.

 * The autohide works automatically handling "delete,request" signals
 * when set to @p true, hidding the window, instead of destroying it.

 * @skip win
 * @until autohide_set

 * Our background will have an image, that will be displayed over the
 * background color.

 * To do so, first we create the background that will display our
 * image.

 * @skipline bg

 * Then, before loading this image, we set the load size of the
 * image. The load size is a hint about the size that we want the
 * image displayed in the screen. It's not the exact size that the
 * image will have, but usually a bit bigger. The background object
 * can still be scaled to a size bigger than the one set here. Setting
 * the image load size to something smaller than its real size will
 * reduce the memory used to keep the pixmap representation of the
 * image, and the time to load it. Here we set the load size to 20x20
 * pixels, but the image is loaded with a size bigger than that (since
 * it's just a hint).
 
 * @skipline load_size_set

 * Now we load our image from it's directory, using file_set. Notice
 * that the second argument of the file_set() function is @c null,
 * since we are setting an image to this background. This function
 * also supports setting an Eet file as background, in which case the
 * @c key parameter wouldn't be @c null, but be the name of the Eet
 * key instead.

 * @skipline file
   
 * To better understand, the function @c size_hint_weight_set for JS
 * bindings originated from C bindings function
 * evas_object_size_hint_weight_set, that is EFL Evas type function.
 * With this function we set the hints for an object's weight.  The
 * parameters are:

 * @li x - Double ranging from 0.0 to 1.0 use as horizontal hint.

 * @li y - Double ranging from 0.0 to 1.0 use as vertical hint.

 * This is not a size enforcement in any way, it's just a hint that
 * should be used whenever appropriate. This is a hint on how a
 * container object should resize a given child within its area.

 * Containers may adhere to the simpler logic of just expanding the
 * child object's dimensions to fit its own or the complete one of
 * taking each child's weight hint as real weights to how much of its
 * size to allocate for them in each axis. A container is supposed to,
 * after normalizing the weights of its children (with weight hints),
 * distribute the space it has to layout them by those factors – most
 * weighted children get larger in this process than the least ones.

 * @skipline weight_set

 * @note Default weight hint values are 0.0, for both axis.

 * Now we add the background as a resize_object to win informing that
 * when the size of the win changes so should the background's
 * size. And finally we make background visible.

 * @skip win
 * @until visible

 * Now we only have to set the size for our window and make it
 * visible.
 
 * @skip size_set
 * @until visible

 * The full code for this example can be found at @ref
 * bg_example_02.js .

 * This example will look like this:

 * @image html screenshots/bg_example_02.png
 * @image latex screenshots/bg_example_02.eps width=\textwidth
 * @example bg_example_02.js
 */

/**
 * @page calendar_js_example_01 Calendar - Simple creation with Javascript Binding
 * @dontinclude calendar_example_01.js

 * As a first example, let's just display a calendar in our window,
 * explaining all steps required to do so.
 
 * The first part consists of including the necessary modules and for
 * this we'll use the Node.js require() function. In this example, we
 * are working solely with elm module.

 * @skipline require

 * Next step is creating an Elementary window with Win_Standard
 * without a parent, which is the type used for all of our
 * examples. Here we also set the title that will appear at the top of
 * our window and then the autohide state for it.
 
 * The autohide works automatically handling "delete,request" signals
 * when set to @p true, hidding the window, instead of destroying it.

 * @skip Win
 * @until autohide_set

 * Now, the exciting part, let's create the calendar with the JS
 * binding method, passing our window object as parent.

 * @skipline Calendar

 * To better understand, the function @c size_hint_weight_set for JS
 * bindings originated from C bindings function
 * evas_object_size_hint_weight_set, that is EFL Evas type function.
 * With this function we set the hints for an object's weight.  The
 * parameters are:

 * @li x - Double ranging from 0.0 to 1.0 use as horizontal hint.

 * @li y - Double ranging from 0.0 to 1.0 use as vertical hint.

 * This is not a size enforcement in any way, it's just a hint that
 * should be used whenever appropriate.

 * This is a hint on how a container object should resize a given
 * child within its area.

 * Containers may adhere to the simpler logic of just expanding the
 * child object's dimensions to fit its own or the complete one of
 * taking each child's weight hint as real weights to how much of its
 * size to allocate for them in each axis. A container is supposed to,
 * after normalizing the weights of its children (with weight hints),
 * distribute the space it has to layout them by those factors – most
 * weighted children get larger in this process than the least ones.

 * @skipline weight_set

 * @note Default weight hint values are 0.0, for both axis.

 * Now we add the calendar as a resize-object to win informing that
 * when the size of the win changes so should the calendar's
 * size. And finally we make our calendar and window visibles.

 * @skip win
 * @until win.visible

 * Our example will look like this:

 * @image html screenshots/calendar_example_01.png

 * @image latex screenshots/calendar_example_01.eps width=\textwidth

 * See the full source code @ref calendar_example_01.js here.

 * @example calendar_example_01.js
 */

/**
 * @page calendar_js_example_03 Calendar - Years restrictions with Javascript Binding
 * @dontinclude calendar_example_03.js

 * This example explains how to set max and min year to be displayed
 * by a calendar object. This means that user won't be able to see or
 * select a date before and after selected years.  By default, limits
 * are 1902 and maximum value will depends on platform architecture
 * (year 2037 for 32 bits); You can read more about time functions on
 * @c ctime manpage.

 * Next step is creating an Elementary window with Win_Standard
 * without a parent, which is the type used for all of our
 * examples. Here we also set the title that will appear at the top of
 * our window and then the autohide state for it.

 * The autohide works automatically handling "delete,request" signals
 * when set to @p true, hidding the window, instead of destroying it.

 * @skip win
 * @until autohide_set
 
 * Now let's create the calendar with the JS binding method, passing
 * our window object as parent.

 * @skipline Calendar

 * To better understand, the function @c size_hint_weight_set for JS
 * bindings originated from C bindings function
 * evas_object_size_hint_weight_set, that is EFL Evas type function.
 * With this function we set the hints for an object's weight.  The
 * parameters are:

 * @li x - Double ranging from 0.0 to 1.0 use as horizontal hint.

 * @li y - Double ranging from 0.0 to 1.0 use as vertical hint.

 * This is not a size enforcement in any way, it's just a hint that
 * should be used whenever appropriate.

 * This is a hint on how a container object should resize a given
 * child within its area.

 * Containers may adhere to the simpler logic of just expanding the
 * child object's dimensions to fit its own or the complete one of
 * taking each child's weight hint as real weights to how much of its
 * size to allocate for them in each axis. A container is supposed to,
 * after normalizing the weights of its children (with weight hints),
 * distribute the space it has to layout them by those factors – most
 * weighted children get larger in this process than the least ones.

 * @skipline weight_set

 * @note Default weight hint values are 0.0, for both axis.

 * Now we add the calendar as a resize-object to win informing that
 * when the size of the win changes so should the calendar's
 * size.

 * @skipline win

 * Straigh to the point, to set the limits for years you need only to
 * call min_max_year_set(). First value is minimum year, second is
 * maximum. If first value is negative, it won't apply limit for min
 * year, if the second one is negative, won't apply for max year.
 * Setting both to negative value will clear limits (default state):

 * @skipline min_max_year_set 

 * Finally we just have to make calendar and window visible.
 
 * @skip cal.visible
 * @until win.visible
 
 * Our example will look like this:

 * @image html screenshots/calendar_example_03.png
 * @image latex screenshots/calendar_example_03.eps width=\textwidth

 * See the full source code @ref calendar_example_03.js here.

 * @example calendar_example_03.js
 */

/**
 * @page datetime_js_example Datetime Example with Javascript Binding
 * @dontinclude datetime_example.js

 * This example places three Elementary Datetime widgets on a window,
 * each of them exemplifying the widget's different usage.

 * The first part consists of including the necessary modules and for
 * this we'll use the Node.js require() function. In this example, we
 * are working with elm and efl modules.
  
 * @skip efl
 * @until elm

 * Next step is creating an Elementary window with Win_Standard
 * without a parent, which is the type used for all of our
 * examples. Here we also set the title that will appear at the top of
 * our window and then the autohide state for it.
 
 * The autohide works automatically handling "delete,request" signals
 * when set to @p true, hidding the window, instead of destroying it.

 * @skip Win
 * @until autohide_set
  
 * Now we construct the elm background and for this we use the JS
 * method below, setting win as it's parent.

 * @skipline elm.Bg

 * To better understand, the function @c size_hint_weight_set for JS
 * bindings originated from C bindings function
 * evas_object_size_hint_weight_set, that is EFL Evas type function.
 * With this function we set the hints for an object's weight.  The
 * parameters are:

 * @li x - Double ranging from 0.0 to 1.0 use as horizontal hint.

 * @li y - Double ranging from 0.0 to 1.0 use as vertical hint.

 * This is not a size enforcement in any way, it's just a hint that
 * should be used whenever appropriate. This is a hint on how a
 * container object should resize a given child within its area.

 * Containers may adhere to the simpler logic of just expanding the
 * child object's dimensions to fit its own or the complete one of
 * taking each child's weight hint as real weights to how much of its
 * size to allocate for them in each axis. A container is supposed to,
 * after normalizing the weights of its children (with weight hints),
 * distribute the space it has to layout them by those factors – most
 * weighted children get larger in this process than the least ones.

 * @skipline weight_set

 * @note Default weight hint values are 0.0, for both axis.

 * Now we add the background as a resize_object to win informing that
 * when the size of the win changes so should the background's
 * size. And finally we make it visible.
 
 * @skip win
 * @until visible 
 
 * @remarks  If a color it's not setted the default color will be used.

 * A box arranges objects in a linear fashion, governed by a layout
 * function that defines the details of this arrangement. The box will
 * use an internal function to set the layout to a single row,
 * vertical by default.

 * Now let's create the box with the JS binding method, passing our
 * window object as parent. Using Evas weight_set function again to
 * hint on how a container object should resize a given child within
 * its area. 

 * @skipline elm.Box
 * @until weight_set

 * Then we add the box as a resize-object to win informing that when
 * the size of the win changes so should the box's size. Remember
 * always to set the box visibility to true.

 * @skip win  
 * @until visible

 * The first of them is <b>"only Date display"</b>. We will create it
 * using the JS method below. The weight hint works with datetime the
 * same as it did with background and box.

 * @skip datetime
 * @until weight

 * Now we have to The function @c size_hint_align_set for JS bindings
 * originated from C bindings function
 * evas_object_size_hint_align_set, that is EFL Evas type
 * function. With this function we set the hints for an object's
 * alignment. The parameters are:
 
 * @li x - Double ranging from 0.0 to 1.0 use as horizontal alignment
 * hint.

 * @li y - Double ranging from 0.0 to 1.0 use as vertical alignment
 * hint.

 * These are hints on how to align an object inside the boundaries of
 * a container/manager. Accepted values are in the 0.0 to 1.0 range,
 * used to specify "justify" or "fill" by some users. In this case,
 * maximum size hints should be enforced with higher priority, if they
 * are set. Also, any padding hint set on objects should add up to the
 * alignment space on the final scene composition.

 * For the horizontal component, 0.0 means to the left, 1.0 means to
 * the right. Analogously, for the vertical component, 0.0 to the top,
 * 1.0 means to the bottom. This is not a size enforcement in any way,
 * it's just a hint that should be used whenever appropriate.

 * @skipline align

 * @note Default alignment hint values are 0.5, for both axis.

 * An important feature for the datetime is the setting of what we
 * want it to display. We can achieve that by using:

 * @p field_visible_set (elm.Elm_Datetime_Field_Type.fieldtype_, visible_)
 
 * Parameters are:

 * @li @p fieldtype_: type of the field, supports 6 fields: 

 * @p year: Indicates Year field.

 * @p month: Indicates Month field.
 
 * @p date: Indicates Date field.

 * @p hour: Indicates Hour field,
 
 * @p minute: Indicates Minute field.

 * @p ampm: Indicates AM/PM field.

 * @li @p visible_: @p true field can be visible, @p false otherwise.

 * @attention Setting this API True does not ensure that the field is
 * visible, apart from this, the field's format must be present in
 * Datetime overall format. If a field's visibility is set to False
 * then it won't appear even though its format is present in overall
 * format. So if and only if this API is set true and the
 * corresponding field's format is present in Datetime format, the
 * field is visible.

 * @note By default the field visibility is set to @p true.

 * For this first datetime we are setting the hour, minute and am/pm
 * to not be visible, doing this we'll display in our datetime the
 * year, month and date.

 * @note Hour format 12hr(1-12) or 24hr(0-23) display can be selected
 * by setting the corresponding user format. The corresponding Month
 * and AM/PM strings are displayed according to the system’s language
 * settings.

 * @skip hour
 * @until ampm
 
 * When using the elm box the packing method of the subobj - datetime
 * in this case - should be defined. There are four possible methods:

 * @li @c pack_start(subobj_) - Add an object to the beginning of the
 * pack list. Pack @c subobj_ into the box obj, placing it first in
 * the list of children objects. The actual position the object will
 * get on screen depends on the layout used. If no custom layout is
 * set, it will be at the top or left, depending if the box is
 * vertical or horizontal, respectively.

 * @li @c pack_end(subobj_) - Add an object at the end of the pack
 * list. Pack @c subobj_ into the box obj, placing it last in the list
 * of children objects. The actual position the object will get on
 * screen depends on the layout used. If no custom layout is set, it
 * will be at the bottom or right, depending if the box is vertical or
 * horizontal, respectively.

 * @li @c pack_before(subobj_, before_) - Adds an object to the box
 * before the indicated object. This will add the @c subobj_ to the
 * box indicated before the object indicated with @c before_. If
 * before is not already in the box, results are undefined. Before
 * means either to the left of the indicated object or above it
 * depending on orientation.
 
 * @li @c pack_after(subobj_, after_) - Adds an object to the box
 * after the indicated object. This will add the @c subobj_ to the box
 * indicated after the object indicated with @c after_. If after is
 * not already in the box, results are undefined. After means either
 * to the right of the indicated object or below it depending on
 * orientation.

 * In this and most examples we use pack_end by choice and
 * practicality. In this part of the code we also make datetime
 * visible.

 * @skip pack_end
 * @until visible

 * For our second datetime, we'll also set the size hints weight and
 * align, but in this case, the fields year, month and date will be not
 * visible, and thus displaying in our datetime the hour, minute and
 * AM/PM. Finally we choose it's packing method and set the visibility
 * of datetime to @p true.

 * @skip datetime
 * @until visible

 * For our third and last datetime, we setted the weight and align as
 * before, chose our packing method and made it visible. Note that in
 * this case we didn't exclude any type of field leaving all
 * visible. Beeing this datetime the last one, here we'll also set win
 * to be visible.
 
 * @skip datetime
 * @until win.visible

 * See the full @ref datetime_example.js .

 * This example should look like:

 * @image html screenshots/datetime_example.png
 * @image latex screenshots/datetime_example.eps width=\textwidth

 * @example datetime_example.js
 */

/**
 * @page clock_js_example Clock widget example with Javascript Binding.
 * @dontinclude clock_example.js
 
 * This code places five Elementary clock widgets on a window, each of
 * them exemplifying a part of the widget's API. Before explaining
 * each clock to be more didatical let's start with the basics.

 * The first part consists of including the necessary modules and for
 * this we'll use the Node.js require() function. In this example, we
 * are working with elm and efl modules.
  
 * @skip efl
 * @until elm
 
 * Next step is creating an Elementary window with Win_Standard
 * without a parent, which is the type used for all of our
 * examples. Here we also set the title that will appear at the top of
 * our window and then the autohide state for it.
 
 * The autohide works automatically handling "delete,request" signals
 * when set to @p true, hidding the window, instead of destroying it.

 * @skip Win
 * @until autohide_set

 * A box arranges objects in a linear fashion, governed by a layout
 * function that defines the details of this arrangement. The box will
 * use an internal function to set the layout to a single row,
 * vertical by default.

 * Now let's create the box with the JS binding method, passing our
 * window object as parent.

 * @skipline elm.Box

 * To better understand, the function @c size_hint_weight_set for JS
 * bindings originated from C bindings function
 * evas_object_size_hint_weight_set, that is EFL Evas type function.
 * With this function we set the hints for an object's weight.  The
 * parameters are:

 * @li x - Double ranging from 0.0 to 1.0 use as horizontal hint.

 * @li y - Double ranging from 0.0 to 1.0 use as vertical hint.

 * This is not a size enforcement in any way, it's just a hint that
 * should be used whenever appropriate. This is a hint on how a
 * container object should resize a given child within its area.

 * Containers may adhere to the simpler logic of just expanding the
 * child object's dimensions to fit its own or the complete one of
 * taking each child's weight hint as real weights to how much of its
 * size to allocate for them in each axis. A container is supposed to,
 * after normalizing the weights of its children (with weight hints),
 * distribute the space it has to layout them by those factors – most
 * weighted children get larger in this process than the least ones.

 * @skipline weight_set

 * @note Default weight hint values are 0.0, for both axis.

 * Then we add the box as a resize-object to win informing that when
 * the size of the win changes so should the box's size. Remember
 * always to set the box visibility to true.

 * @skip win  
 * @until visible

 * We create each clock with the JS binding method, passing our
 * window object as parent. The first of them is the pristine clock,
 * using the defaults for a clock, which are military time with no
 * seconds shown.
 
 * @skipline Clock

 * When using the elm.Box the packing method of the subobj - clock
 * in this case - should be defined. There are four possible methods:

 * @li @c pack_start(subobj_) - Add an object to the beginning of the
 * pack list. Pack @c subobj_ into the box obj, placing it first in
 * the list of children objects. The actual position the object will
 * get on screen depends on the layout used. If no custom layout is
 * set, it will be at the top or left, depending if the box is
 * vertical or horizontal, respectively.

 * @li @c pack_end(subobj_) - Add an object at the end of the pack
 * list. Pack @c subobj_ into the box obj, placing it last in the list
 * of children objects. The actual position the object will get on
 * screen depends on the layout used. If no custom layout is set, it
 * will be at the bottom or right, depending if the box is vertical or
 * horizontal, respectively.

 * @li @c pack_before(subobj_, before_) - Adds an object to the box
 * before the indicated object. This will add the @c subobj_ to the
 * box indicated before the object indicated with @c before_. If
 * before is not already in the box, results are undefined. Before
 * means either to the left of the indicated object or above it
 * depending on orientation.
 
 * @li @c pack_after(subobj_, after_) - Adds an object to the box
 * after the indicated object. This will add the @c subobj_ to the box
 * indicated after the object indicated with @c after_. If after is
 * not already in the box, results are undefined. After means either
 * to the right of the indicated object or below it depending on
 * orientation.

 * In this and most examples we use pack_end by choice and
 * practicality. In this part of the code we also make clock
 * visible.

 * @skip pack_end
 * @until visible

 * The second clock shows ther am/pm time, that we also create with
 * the JS binding method, passing our window object as
 * parent. Setting show_am_pm to true and again choosing the packing
 * method and making clock visible.

 * @skip Clock
 * @until visible

 * The third one will show the seconds digits, which will flip in
 * synchrony with system time. Note, besides, that the time itself is
 * @b different from the system's -- it was customly set with
 * time_set():

 * @skip ck3
 * @until visible

 * In both fourth and fifth ones, we turn on the <b>edition
 * mode</b>. See how you can change each of the sheets on it, and be
 * sure to try holding the mouse pressed over one of the sheet
 * arrows. The forth one also starts with a custom time set:

 * @skip ck4
 * @until visible

 * The fifth, besides editable, it has only the time @b units
 * editable, for hours, minutes and seconds. For this we used
 * edit_mode_set with the parameter digedit that sets indentifiers for
 * which clock digits should be editable, when a clock widget is in
 * edition mode. Values may be OR-ed together to make a mask,
 * naturally. 

 * Possible values for digedit:

 * @li @p default: Default value. Means that all digits are
 * editable, when in edition mode.

 * @li @p hour_decimal: Decimal digit of hours value should
 * be editable;

 * @li @p hour_unit: Unit digit of hours value should be
 * editable;

 * @li @p min_decimal: Decimal digit of minutes value should
 * be editable;

 * @li @p min_unit: Unit digit of minutes value should be
 * editable;

 * @li @p sec_decimal: Decimal digit of seconds value should
 * be editable;

 * @li @p sec_unit: Unit digit of seconds value should be
 * editable;

 * @li @p all: All digits should be editable;

 * Finishing this example we should set win to be visible.

 * @skip ck5
 * @until win.visible

 * See the full @ref clock_example.js, whose window should look
 * like this picture:

 * @image html screenshots/clock_example.png
 * @image latex screenshots/clock_example.eps width=\textwidth
 * @example clock_example.js
 */

/**
 * @page separator_js_example_01  Separator with Javascript Binding
 * @dontinclude separator_example_01.js

 * Separator is a very thin object used to separate other objects,
 * wich can be vertical or horizontal.

 * This example shows how to create a window and separate in two
 * parts, each one will be filled with a background color to show the
 * division. The @a separator is used to visually mark the division
 * between two parts.

 * The first part consists of including the necessary modules and for
 * this we'll use the Node.js require() function. In this example, we
 * are working with elm and efl modules.
  
 * @skip efl
 * @until elm
 
 * Next step is creating an Elementary window with Win_Standard
 * without a parent, which is the type used for all of our
 * examples. Here we also set the title that will appear at the top of
 * our window and then the autohide state for it.
 
 * The autohide works automatically handling "delete,request" signals
 * when set to @p true, hidding the window, instead of destroying it.

 * @skip win
 * @until autohide_set

 * Now let's create the background with the JS binding method, passing
 * our window as parent.

 * @skipline bg

 * To better understand, the function @c size_hint_weight_set for JS
 * bindings originated from C bindings function
 * evas_object_size_hint_weight_set, that is EFL Evas type function.
 * With this function we set the hints for an object's weight.  The
 * parameters are:

 * @li x - Double ranging from 0.0 to 1.0 use as horizontal hint.

 * @li y - Double ranging from 0.0 to 1.0 use as vertical hint.

 * This is not a size enforcement in any way, it's just a hint that
 * should be used whenever appropriate. This is a hint on how a
 * container object should resize a given child within its area.

 * Containers may adhere to the simpler logic of just expanding the
 * child object's dimensions to fit its own or the complete one of
 * taking each child's weight hint as real weights to how much of its
 * size to allocate for them in each axis. A container is supposed to,
 * after normalizing the weights of its children (with weight hints),
 * distribute the space it has to layout them by those factors – most
 * weighted children get larger in this process than the least ones.

 * @skipline weight_set

 * @note Default weight hint values are 0.0, for both axis.

 * Now we add the background as a resize-object to win informing that
 * when the size of the win changes so should the background's size
 * and setting it's visibility. You can change the background's color
 * using color_set, if not, the default color will be used.
 
 * @skip win
 * @until visible
 
 * To put a box in the window we also need to set it's parent. By
 * default, box object arranges their contents vertically from top to
 * bottom. By calling this function with horizontal as @a true, the
 * box will become horizontal, arranging contents from left to right.

 * @skip bx
 * @until horizontal

 * The value that we set EFL Evas function size_hint_weight_set
 * expands the box to cover all win's area and adding it as a
 * resize_object to win informing that when the size of the win
 * changes so should the box's size. In the end we make the box
 * visible.
 
 * @skip weight
 * @until visible
  
 * Now we create a retangle, like before, we just need to setting it's
 * parent. After created, we set the color to show the difference
 * between the next rectangle and define the minimun size of each side
 * by using size_hint_min_set(minimum width, minimum height).

 * @skip rect
 * @until min_set

 * As in the background, the value we set EFL Evas function
 * size_hint_weight_set expands the background to cover all area
 * defined in size_hint_min_set. We also need to expand the rectangle
 * to fill the area if the win's size change, if not, win can change
 * it's size and the rectangle will only fill it's own previous area.

 * @until weight

 * Now we have to The function @c size_hint_align_set for JS bindings
 * originated from C bindings function
 * evas_object_size_hint_align_set, that is EFL Evas type
 * function. With this function we set the hints for an object's
 * alignment. The parameters are:
 
 * @li x - Double ranging from 0.0 to 1.0 use as horizontal alignment
 * hint.

 * @li y - Double ranging from 0.0 to 1.0 use as vertical alignment
 * hint.

 * These are hints on how to align an object inside the boundaries of
 * a container/manager. Accepted values are in the 0.0 to 1.0 range,
 * used to specify "justify" or "fill" by some users. In this case,
 * maximum size hints should be enforced with higher priority, if they
 * are set. Also, any padding hint set on objects should add up to the
 * alignment space on the final scene composition.

 * For the horizontal component, 0.0 means to the left, 1.0 means to
 * the right. Analogously, for the vertical component, 0.0 to the top,
 * 1.0 means to the bottom. This is not a size enforcement in any way,
 * it's just a hint that should be used whenever appropriate.

 * @skipline align

 * @note Default alignment hint values are 0.5, for both axis.

 * Now we only need to set the visibility of the rectangle and add our
 * retangle to box with the packing method of the subobj - rectangle
 * in this case. There are four possible methods:

 * @li @c pack_start(subobj_) - Add an object to the beginning of the
 * pack list. Pack @c subobj_ into the box obj, placing it first in
 * the list of children objects. The actual position the object will
 * get on screen depends on the layout used. If no custom layout is
 * set, it will be at the top or left, depending if the box is
 * vertical or horizontal, respectively.

 * @li @c pack_end(subobj_) - Add an object at the end of the pack
 * list. Pack @c subobj_ into the box obj, placing it last in the list
 * of children objects. The actual position the object will get on
 * screen depends on the layout used. If no custom layout is set, it
 * will be at the bottom or right, depending if the box is vertical or
 * horizontal, respectively.

 * @li @c pack_before(subobj_, before_) - Adds an object to the box
 * before the indicated object. This will add the @c subobj_ to the
 * box indicated before the object indicated with @c before_. If
 * before is not already in the box, results are undefined. Before
 * means either to the left of the indicated object or above it
 * depending on orientation.
 
 * @li @c pack_after(subobj_, after_) - Adds an object to the box
 * after the indicated object. This will add the @c subobj_ to the box
 * indicated after the object indicated with @c after_. If after is
 * not already in the box, results are undefined. After means either
 * to the right of the indicated object or below it depending on
 * orientation.

 * In this and most examples we use pack_end by choice and
 * practicality.
 
 * @skip visible
 * @until pack
 
 * Once we have our first rectangle in the box we create and add our
 * separator. Using the same approach, we setting it's parent. Since
 * our box is in horizontal mode it's a good idea to set the separator
 * to be horizontal too. Finishing with the visibility and packing
 * method.

 * @skip separator
 * @until pack

 * After all this, we just need to create another rectangle, setting
 * the color, size hints, make rect2 visible and packing in the
 * box. Don't forget to set the win's visibility as @p true.

 * @skip rect2
 * @until win.visible

 * The full code for this example can be found at @ref separator_example_01.js .

 * This example will look like:

 * @image html screenshots/separator_example_01.png
 * @image latex screenshots/separator_example_01.eps width=\textwidth

 * @example separator_example_01.js
 */


/**
 * @page icon_js_example_01 Icon Example with Javascript Binding
 * @dontinclude icon_example_01.js

 * This example is as simple as possible. An icon object will be added
 * to the window over a blank background, and set to be resizable
 * together with the window. All the options set through the example
 * will affect the behavior of this icon.

 * The first part consists of including the necessary modules and for
 * this we'll use the Node.js require() function. In this example, we
 * are working with elm and efl modules.
  
 * @skip efl
 * @until elm

 * Next step is creating an Elementary window with Win_Standard
 * without a parent, which is the type used for all of our
 * examples. Here we also set the title that will appear at the top of
 * our window and then the autohide state for it.
 
 * The autohide works automatically handling "delete,request" signals
 * when set to @p true, hidding the window, instead of destroying it.

 * @skip win
 * @until autohide_set

 * Now we construct the elm icon and for this we use the JS method
 * below, setting it's parent. An icon object is used to display
 * standard icon images ("delete", "edit", "arrows", etc.) or images
 * coming from a custom file (PNG, JPG, EDJE, etc.), on icon contexts.

 * @skipline icon

 * Now we can set the standard "home" icon, chosen for this example.
  
 * @skipline standard

 * An interesting thing is that after setting this, it's possible to
 * check where in the filesystem is the theme used by this icon, and
 * the name of the group used, using file_get. Note that when a
 * function get returns two parameters, they are therefore stored in a
 * array, following the same order as the function.
 
 * @skip path
 * @until console

 * We can also get the name of the standard icon that we setted
 * before.

 * @skip name
 * @until console

 * We can now go setting our options.
 
 * no_scale_set() is used just to set this value to true as we don't
 * actually want to scale our icon, just resize it.
 
 * resizable_set() is used to allow the icon to be resized to a size
 * smaller than the original one, but not to a size bigger than it.
 
 * smooth_set() will disable the smooth scaling, so the scale
 * algorithm used to scale the icon to the new object size is going to
 * be faster, but with a lower quality.
 
 * fill_outside_set() is used to ensure that the icon will fill the
 * entire area available to it, even if keeping the aspect ratio. The
 * icon will overflow its width or height (any of them that is
 * necessary) to the object area, instead of resizing the icon down
 * until it can fit entirely in this area.
 
 * This is the code for setting these options:
 
 * @until fill_outside
 
 * However, if you try this example you may notice that this image is
 * not being affected by all of these options. This happens because
 * the used icon will be from elementary theme, and thus it has its
 * own set of options like smooth scaling and fill_outside
 * options. You can change the "home" icon to use some image (from
 * your system) and see that then those options will be respected.
 
 * To better understand, the function @c size_hint_weight_set for JS
 * bindings originated from C bindings function
 * evas_object_size_hint_weight_set, that is EFL Evas type function.
 * With this function we set the hints for an object's weight.  The
 * parameters are:

 * @li x - Double ranging from 0.0 to 1.0 use as horizontal hint.

 * @li y - Double ranging from 0.0 to 1.0 use as vertical hint.

 * This is not a size enforcement in any way, it's just a hint that
 * should be used whenever appropriate. This is a hint on how a
 * container object should resize a given child within its area.

 * Containers may adhere to the simpler logic of just expanding the
 * child object's dimensions to fit its own or the complete one of
 * taking each child's weight hint as real weights to how much of its
 * size to allocate for them in each axis. A container is supposed to,
 * after normalizing the weights of its children (with weight hints),
 * distribute the space it has to layout them by those factors – most
 * weighted children get larger in this process than the least ones.

 * @skipline weight_set

 * @note Default weight hint values are 0.0, for both axis.

 * Now we add the icon as a resize_object to win informing that
 * when the size of the win changes so should the icon's
 * size. And finally we make icon visible. 

 * @skip resize
 * @until visible

 * Now we set the size for the window, making it visible in the end:
 
 * @skip size_set
 * @until visible
 
 * The full code for this example can be found at @ref icon_example_01.js
 
 * This example will look like this:
 
 * @image html screenshots/icon_example_01.png
 * @image latex screenshots/icon_example_01.eps width=\textwidth
 
 * @example icon_example_01.js
 */