mirrors/eiffel-org
1
0
Fork 0
mirror of https://github.com/EiffelSoftware/eiffel-org.git synced 2025-12-06 14:52:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

Author:halw

Browse Source 
Date:2008-10-25T08:00:01.000000Z


git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@98 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
halw
2008-10-25 08:00:01 +00:00
parent 19bcd2b1ec
commit e87454a2ed
16 changed files with 242 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
documentation/current/solutions/basic-computing/eiffelbase/eiffelbase-tutorial/eiffelbase-data-structures-overview/eiffelbase-data-structures-lists.wiki
View File

@@ -14,8 +14,7 @@ The list and chain classes are characterized, for their traversal properties, as
[[ref:/libraries/base/reference/linear_chart|LINEAR]] describes sequential structures that may be traversed one way. It introduces in particular the following features, illustrated on the figure below:
* <eiffel>after</eiffel>, a boolean-valued query which determines whether you have moved past the last position (a more precise specification is given below).
* <eiffel>off</eiffel>, a boolean-valued query which is false if and only if there is no item at the current position; for [[ref:/libraries/base/reference/linear_chart|LINEAR]] this is the same as:
<code>
is_empty and not after</code>
<code>is_empty and not after</code>
* <eiffel>item</eiffel>, a query which returns the item at the current position - provided of course there is one, as expressed by the precondition:
<code>
@@ -207,12 +206,10 @@ first. The symmetric property applies to <eiffel>back</eiffel>. The cyclic natur
<code>not after</code>
Similarly, the precondition for back is
<code>
not before</code>
<code>not before</code>
For lists, after becomes true when the cursor moves past the last item. For circular chains, however, after and before are never true except for an empty structure; this is expressed by the invariant clauses of class [[ref:/libraries/base/reference/circular_chart|CIRCULAR]] :
<code>
not before</code>
<code>not before</code>
For a non-empty circular chain, then, you can circle forever around the items, using forth or back.
@@ -223,45 +220,46 @@ A circular chain also needs a notion of first item, if only to enable a client t
For circular chains, however, there is no reason why the first item should always remain the same. One of the benefits that clients may expect from the use of a circular <br/>
structure is the ability to choose any item as the logical first. Class [[ref:/libraries/base/reference/circular_chart|CIRCULAR]] offers for that purpose the procedure <eiffel>set_start</eiffel> which designates the current cursor position as the first in the circular chain. Subsequent calls to <eiffel>start</eiffel> will move the cursor to this position; calls to <eiffel>finish</eiffel> will move the cursor to the cyclically preceding position. With most implementations, there will then be two notions of first position: the logical first, which clients may freely choose through calls to <eiffel>set_start</eiffel>; and the <eiffel>physical first</eiffel>, which results from the implementation. In a representation using an array with indices from 1 to <eiffel>capacity</eiffel>, for example, the physical first is position 1, and the logical first may be any index in the permitted range. In a linked representation, there will be a cell first element corresponding to the physical first, but the logical first is any cell in the chain. <br/>
In such cases the circular chain classes have features called <eiffel>standard_first</eiffel>, <eiffel>standard_last</eiffel>, <eiffel>standard_start</eiffel> and so on, which are not exported (so that you will not see them in the flat-short forms) but serve to implement visible features such as <eiffel>first</eiffel>, <eiffel>last</eiffel> and <eiffel>forth</eiffel>. For example a possible implementation of <eiffel>forth</eiffel> for circular chains is
<code>
forth
-- Move cursor to next item, cyclically.
do
standard_forth
if standard_after then
standard_start
end
if isfirst then
exhausted := True
end
end</code>
<code>forth is
-- Move cursor to next item, cyclically.
do
standard_forth
if standard_after then
standard_start
end
if isfirst then
exhausted := True
end
end</code>
==Traversing a list or circular chain==
The properties of <eiffel>forth</eiffel> for circular chains imply that a traversal loop written as
<code>
from
lin.start
until
lin.off
loop
...
lin.forth
end</code>
<code>from
lin.start
until
lin.off
loop
...
lin.forth
end</code>
would not work if <code>lin</code> is a non-empty circular structure: <eiffel>off</eiffel> would never become true, so that the loop would forever cycle over the structure's items. The same would apply to a loop using finish and back instead of <eiffel>start</eiffel> and <eiffel>forth</eiffel>. This behavior is the natural result of the semantics defined for <eiffel>off</eiffel> , <eiffel>forth</eiffel> and <eiffel>back</eiffel> for circular structures. But it prevents us from using these features to perform a single traversal which will visit every item once. <br/>
Using <eiffel>exhausted</eiffel> in lieu of off solves this problem. In class [[ref:/libraries/base/reference/circular_chart|CIRCULAR]] , <eiffel>exhausted</eiffel> is an attribute which is set to false by <eiffel>start</eiffel> and <eiffel>finish</eiffel>, and is set to true by <eiffel>forth</eiffel> when advancing from the last item to the first and by <eiffel>back</eiffel> when backing up from the first item to the last. So you should write the loop as
<code>
from
lin.start
some_optional_initializing_operation (lin)
until
lin.exhausted
loop
...
lin.some_action (lin.item)
lin.forth
end</code>
<code>from
lin.start
some_optional_initializing_operation (lin)
until
lin.exhausted
loop
...
lin.some_action (lin.item)
lin.forth
end</code>
This form is applicable to all linear structures, circular or not, since <eiffel>exhausted</eiffel> is introduced in class [[ref:/libraries/base/reference/linear_chart|LINEAR]] as a function which returns the same value as <eiffel>off</eiffel> .Its redefinition into an attribute, modified by <eiffel>start</eiffel>,<eiffel> finish</eiffel>, <eiffel>forth</eiffel> and <eiffel>back</eiffel>, does not occur until class [[ref:/libraries/base/reference/circular_chart|CIRCULAR]] . <br/>
Because <eiffel>exhausted</eiffel> is more general than <eiffel>off</eiffel> , the iteration scheme just given (and its equivalent going backwards) is preferable to the earlier one using <eiffel>off </eiffel>, especially if there is any chance that the iteration might one day be applied to a lin structure that is circular. Classes of the Iteration library, in particular [[ref:/libraries/base/reference/linear_iterator_chart|LINEAR_ITERATOR]] , rely on this scheme for iterating over linear structures.
@@ -315,7 +313,7 @@ A similar implementation is used for two-way-linked structures such as two-way l
The classes describing list cells are descendants of a deferred class called [[ref:/libraries/base/reference/cell_chart|CELL]] , whose features are:
* <eiffel>item</eiffel>, the contents of the cell.
* <eiffel>put </eiffel> <code>(v : like</code> <eiffel>item</eiffel><code>)</code>, which replaces the contents of the cell by a new value.
* <eiffel>put </eiffel> <code>( v :</code> <code>like </code> <eiffel>item</eiffel> <code>)</code>, which replaces the contents of the cell by a new value.
Class [[ref:/libraries/base/reference/linkable_chart|LINKABLE]] is an effective descendant of [[ref:/libraries/base/reference/cell_chart|CELL]] , used for one-way linked structures. It introduces features <eiffel>right</eiffel>, a reference to another cell to which the current <br/>
cell will be linked. Two-way linked structures use [[ref:/libraries/base/reference/bi_linkable_chart|BI_LINKABLE]] , an heir of [[ref:/libraries/base/reference/linkable_chart|LINKABLE]] which to the above features adds <eiffel>left</eiffel>, a reference to the preceding cell in the structure.
@@ -323,12 +321,11 @@ cell will be linked. Two-way linked structures use [[ref:/libraries/base/referen
{{caution|Do not confuse the <eiffel>item</eiffel> feature of [[ref:/libraries/base/reference/cell_chart|CELL]] and its descendants, such as [[ref:/libraries/base/reference/linkable_chart|LINKABLE]] , with the <eiffel>item</eiffel> feature of the classes describing linear structures, such as [[ref:/libraries/base/reference/linked_list_chart|LINKED_LIST]] . For a linked list, <eiffel>item</eiffel> returns the item at cursor position. }}
It may be implemented as
<code>
item: G
-- Current item
do
Result := active.item
end</code>
<code>item: G is
-- Current item
do
Result := active.item
end</code>
using the <eiffel>item</eiffel> feature of [[ref:/libraries/base/reference/linkable_chart|LINKABLE]] , applied to <eiffel>active</eiffel>.
@@ -363,13 +360,12 @@ divided into a number of blocks. Each block is an array, but the successive arra
=Sorted Linear Structures=
The class [[ref:/libraries/base/reference/comparable_struct_chart|COMPARABLE_STRUCT]] , an heir of [[ref:/libraries/base/reference/bilinear_chart|BILINEAR]] , is declared as
<code>
deferred class
COMPARABLE_STRUCT [G -> COMPARABLE]
inherit
BILINEAR
feature
...</code>
<code>deferred class
COMPARABLE_STRUCT [G -> COMPARABLE]
inherit
BILINEAR
feature
...</code>
As indicated by the constrained generic parameter it describes bilinear structures whose items may be compared by a total order relation.
@@ -378,9 +374,8 @@ As indicated by the constrained generic parameter it describes bilinear structur
COMPARABLE_STRUCT introduces the features <eiffel>min</eiffel> and <eiffel>max</eiffel>, giving access to the minimum and maximum elements of a structure; these are always present for a finite <br/>
structure with a total order relation. [[ref:/libraries/base/reference/sorted_struct_chart|SORTED_STRUCT]] , an heir of [[ref:/libraries/base/reference/comparable_struct_chart|COMPARABLE_STRUCT]] , describes structures that can be sorted; it introduces the query sorted and the command sort. <br/>
The deferred class [[ref:/libraries/base/reference/part_sorted_list_chart|PART_SORTED_LIST]] describes lists whose items are kept ordered in a way that is compatible with a partial order relation defined on them. The class is declared as
<code>
deferred class
PART_SORTED_LIST [G -> COMPARABLE]...</code>
<code>deferred class
PART_SORTED_LIST [G -> COMPARABLE]...</code>
An implementation based on two-way linked lists is available through the effective heir [[ref:/libraries/base/reference/sorted_two_way_list_chart|SORTED_TWO_WAY_LIST]] . <br/>
The deferred class [[ref:/libraries/base/reference/sorted_list_chart|SORTED_LIST]] , which inherits from [[ref:/libraries/base/reference/part_sorted_list_chart|PART_SORTED_LIST]] , assumes that the order relation on G is a total order. As a result, the class is able to introduce features <eiffel>min</eiffel>, <eiffel>max</eiffel> and <eiffel>median</eiffel>. Here too a two-way linked list implementation is available, through the effective class [[ref:/libraries/base/reference/sorted_two_way_list_chart|SORTED_TWO_WAY_LIST]] .

74
documentation/current/solutions/basic-computing/eiffelbase/eiffelbase-tutorial/eiffelbase-kernel.wiki
View File

@@ -58,10 +58,6 @@ end
The features of [[ref:/libraries/base/reference/any_chart|ANY]] are usable in both qualified and unqualified form. For example, the argumentless function out, which produces a printable representation of any object, may be called under either of the forms
<code>
x := out
@@ -298,9 +294,9 @@ The argument indicates the number of characters for the initial allocation. This
The object attached at run-time to an entity such declared of type [[ref:/libraries/base/reference/string_8_chart|STRING]] is not the actual sequence of characters but a string descriptor, which contains a reference to the actual string contents.
As a result, four assignment or assignment-like operations are possible:
* '''A1''' <code>s1 := s</code>
* '''A1''' <code>s1 := s</code>
* '''A2''' <code>s2.share (s)</code>
* '''A3''' <code>s3 := s.twin</code>
* '''A3''' <code>s3 := s.twin</code>
* '''A4''' <code>s4.copy (s)</code>
As illustrated below, ''' A1''' is a reference assignment: <code>s1</code> will be attached to the same descriptor as s. ''' A2''' keeps the descriptors distinct, but make them refer to the same sequence of characters. In ''' A3''', <code>s3</code> will be attached to a new string, completely distinct from the string attached to <code>s1</code> although made of identical characters. ''' A4''' has almost the same effect as '''A3''', but is only applicable if <code>s4</code> was not void, and will override the existing descriptor rather than creating a new one.
@@ -384,41 +380,41 @@ Sometime you will be in a position where the schema of a class will have changed
The storable mechanism allows you to retrieve the old version of the object only if it was saved using the <eiffel>independent_store</eiffel> facility. Each time you retrieve an object of a certain base class whose schema has changed, the feature <eiffel>correct_mismatch</eiffel> will be called. This feature is defined in [[ref:/libraries/base/reference/any_chart|ANY]] and by default will raise an exception. To handle the mismatch, you need to redefine <eiffel>correct_mismatch</eiffel> in the base class whose schema has been changed. For example in EiffelBase, [[ref:/libraries/base/reference/hash_table_chart|HASH_TABLE]] has changed between version 5.1 and version 5.2 to use <eiffel> SPECIAL</eiffel> rather than [[ref:/libraries/base/reference/array_chart|ARRAY]] for its internal data storage. To retrieve a 5.1 version of [[ref:/libraries/base/reference/hash_table_chart|HASH_TABLE]], you need to define <eiffel>correct_mismatch</eiffel> as following:
<code>
correct_mismatch is
-- Attempt to correct object mismatch during retrieve using `mismatch_information'.
local
array_content: ARRAY [G]
array_keys: ARRAY [H]
array_marks: ARRAY [BOOLEAN]
do
-- In version 5.1 and earlier, `content', `keys' and `deleted_marks'
-- where of base class [[ref:/libraries/base/reference/array_chart|ARRAY]] . In 5.2 we changed it to be a SPECIAL for
-- efficiency reasons. In order to retrieve an old [[ref:/libraries/base/reference/hash_table_chart|HASH_TABLE]] we
-- need to convert those [[ref:/libraries/base/reference/array_chart|ARRAY]] instances into SPECIAL instances.
-- Attempt to correct object mismatch during retrieve using `mismatch_information'.
local
array_content: ARRAY [G]
array_keys: ARRAY [H]
array_marks: ARRAY [BOOLEAN]
do
-- In version 5.1 and earlier, `content', `keys' and `deleted_marks'
-- were of base class ARRAY. In 5.2 we changed it to be a SPECIAL for
-- efficiency reasons. In order to retrieve an old HASH_TABLE we
-- need to convert those ARRAY instances into SPECIAL instances.
-- Convert `content' from [[ref:/libraries/base/reference/array_chart|ARRAY]] to SPECIAL
array_content ?= mismatch_information.item ("content")
if array_content /= Void then
content := array_content.area
end
-- Convert `content' from ARRAY to SPECIAL
array_content ?= mismatch_information.item ("content")
if array_content /= Void then
content := array_content.area
end
-- Convert `keys' from [[ref:/libraries/base/reference/array_chart|ARRAY]] to SPECIAL
array_keys ?= mismatch_information.item ("keys")
if array_keys /= Void then
keys := array_keys.area
end
-- Convert `keys' from ARRAY to SPECIAL
array_keys ?= mismatch_information.item ("keys")
if array_keys /= Void then
keys := array_keys.area
end
-- Convert `deleted_marks' from [[ref:/libraries/base/reference/array_chart|ARRAY]] to SPECIAL
array_marks ?= mismatch_information.item ("deleted_marks")
if array_marks /= Void then
deleted_marks := array_marks.area
end
-- Convert `deleted_marks' from ARRAY to SPECIAL
array_marks ?= mismatch_information.item ("deleted_marks")
if array_marks /= Void then
deleted_marks := array_marks.area
end
if content = Void or keys = Void or deleted_marks = Void then
-- Could not retrieve old version of [[ref:/libraries/base/reference/hash_table_chart|HASH_TABLE]] . We throw an exception.
Precursor {TABLE}
end
end
</code>
if content = Void or keys = Void or deleted_marks = Void then
-- Could not retrieve old version of HASH_TABLE. We throw an exception.
Precursor {TABLE}
end
end
</code>
Note the use of <eiffel>mismatch_information</eiffel>, this is a once feature of [[ref:/libraries/base/reference/any_chart|ANY]] of type <eiffel>MISMATCH_INFORMATION</eiffel> which behaves like a [[ref:/libraries/base/reference/hash_table_chart|HASH_TABLE]]. The keys of the table are the names of the attributes on which a mismatch occurred and the values are the corresponding object fields as they were originally stored. In this particular case of [[ref:/libraries/base/reference/hash_table_chart|HASH_TABLE]] we know that the previous version was an [[ref:/libraries/base/reference/array_chart|ARRAY]], so we do an assignment attempt and if it succeeds we assign its <eiffel>area</eiffel> to the corresponding attribute of [[ref:/libraries/base/reference/hash_table_chart|HASH_TABLE]].
@@ -449,7 +445,7 @@ As you will see from the header comments in the flat-short form of class [[ref:/
The features of class [[ref:/libraries/base/reference/exceptions_chart|EXCEPTIONS]] enable you to determine whether a certain exception is a signal - an operating system event such as may result from a child process that disappears, a window that is resized, a user that hits the Break key and many others. But they do not give you more details because the exact set of possible signals is highly platform-dependent. <br/>
Class [[ref:/libraries/base/reference/unix_signals_chart|UNIX_SIGNALS]] complements EXCEP_CONST by providing codes for the signals of Unix and similar systems, such as Sigkill for the 'kill' signal and Sigbus for bus error. <br/>
Query <eiffel>is_defined </eiffel> <code>(</code> <code>some_signal</code> <code>)</code>, where <code>some_signal</code> is an integer code, will determine whether some_signal is supported on the platform. <br/>
Query <eiffel>is_defined </eiffel> <code>(some_signal)</code>, where <code>some_signal</code> is an integer code, will determine whether some_signal is supported on the platform. <br/>
A class whose routines need to perform specific processing depending on the nature of signals received should inherit from [[ref:/libraries/base/reference/unix_signals_chart|UNIX_SIGNALS]] , or a similar class for another platform. <br/>
Because signal codes are platform-dependent, the features of [[ref:/libraries/base/reference/unix_signals_chart|UNIX_SIGNALS]] are implemented as once functions - computed on the first call - rather than constants, although this makes no difference to clients.
@@ -469,7 +465,7 @@ Writing, assembling and compiling a system yields an executable command. The sys
<code>your_system arg1 arg2 arg3</code>
although one may conceive of other ways of entering the command arguments, such as tabular or graphical form-filling. In any case the software must be able to access the values passed as command arguments. <br/>
A language mechanism is available for that purpose: the Root Class rule indicates that the creation procedure of the root class may have a single argument (in the Eiffel sense of argument to a routine) of type [[ref:/libraries/base/reference/array_chart|ARRAY]] [ [[ref:/libraries/base/reference/string_8_chart|STRING]] <code>]</code>. The corresponding array of strings will be initialized at the beginning of the system's execution with the values entered as arguments to that execution of the command. <br/>
A language mechanism is available for that purpose: the Root Class rule indicates that the creation procedure of the root class may have a single argument (in the Eiffel sense of argument to a routine) of type <code>ARRAY[STRING]</code>. The corresponding array of strings will be initialized at the beginning of the system's execution with the values entered as arguments to that execution of the command. <br/>
Although this facility suffices in many cases, it is not always convenient if you suddenly need to access the command arguments in a class that is far-away from the root. An alternative mechanism, class ARGUMENTS, is available. Once again, this is a class from which you should inherit if you need its facilities. It has just two exported features:
* <eiffel>argument_count</eiffel>, a non-negative integer, is the number of command arguments.
* <eiffel>argument</eiffel> <code>(</code>i<code>)</code>, a string, is the i-th command argument. Here <code>i</code> must be between 0 and <eiffel>argument_count</eiffel>; the convention is that for <code>i </code> <code>= 0</code> the result is the name of the command itself.

34
documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/absolute-time.wiki
View File

@@ -3,17 +3,17 @@
[[Property:uuid|195849fc-1a9c-d734-2d2b-acae78133886]]
The classes dealing with date and those dealing with time have almost the same construction. At the top of the hierarchy are the constants and the notion of value ([[ref:libraries/time/reference/time_value_chart|TIME_VALUE]] , [[ref:libraries/time/reference/date_value_chart|DATE_VALUE]] , [[ref:libraries/time/reference/date_time_value_chart|DATE_TIME_VALUE]] ). From this notion come two kinds of heirs which are the absolute notion of time (classes [[ref:libraries/time/reference/date_chart|DATE]] , [[ref:libraries/time/reference/time_chart|TIME]] and [[ref:libraries/time/reference/date_time_chart|DATE_TIME]] ) and the notion of duration (classes [[ref:libraries/time/reference/date_duration_chart|DATE_DURATION]] , [[ref:libraries/time/reference/time_duration_chart|TIME_DURATION]] , [[ref:libraries/time/reference/date_time_duration_chart|DATE_TIME_DURATION]] ).
[[ref:libraries/time/reference/date_chart|DATE]] , [[ref:libraries/time/reference/time_chart|TIME]] and [[ref:libraries/time/reference/date_time_chart|DATE_TIME]] inherit from the deferred class <eiffel>ABSOLUTE</eiffel>. It implies that instances of these classes are used as absolutes. We can imagine an oriented axis on which are reported values. <eiffel>ABSOLUTE </eiffel>inherits <eiffel>COMPARABLE</eiffel>, there is a complete order inside the class and its heir. <eiffel>ABSOLUTE</eiffel> is a client of <eiffel>DURATION</eiffel>, so that each instance of <eiffel>ABSOLUTE </eiffel>is linked with the duration between the origin and itself.
[[ref:libraries/time/reference/date_chart|DATE]] , [[ref:libraries/time/reference/time_chart|TIME]] and [[ref:libraries/time/reference/date_time_chart|DATE_TIME]] inherit from the deferred class <eiffel>ABSOLUTE</eiffel>. It implies that instances of these classes are used as absolutes. We can imagine an oriented axis on which are reported values. <eiffel>ABSOLUTE</eiffel> inherits <eiffel>COMPARABLE</eiffel>, there is a complete order inside the class and its heir. <eiffel>ABSOLUTE</eiffel> is a client of <eiffel>DURATION</eiffel>, so that each instance of <eiffel>ABSOLUTE</eiffel> is linked with the duration between the origin and itself.
The default way to compare absolute objects is to compare their respective duration to each other.
==TIME==
[[ref:libraries/time/reference/time_chart|TIME]] deals with hour, minute and second. Is is possible to use more precision for time (there is no limit inside the class). See More precision in <eiffel>TIME</eiffel> for documentation. This section deals only with second.
[[ref:libraries/time/reference/time_chart|TIME]] deals with hour, minute, and second. It is possible to use more precision for time (there is no limit inside the class). See More precision in <eiffel>TIME</eiffel> for documentation. This section deals only with second.
====Creation====
There are three ways to create an instance of the class <eiffel>TIME</eiffel>: by choosing the time (make), by getting the time from the system (make_now), or by choosing the number of seconds elapsed from the origin (make_by_seconds). The arguments of make and make_by_seconds have to respect the range of a day (see preconditions).
There are three ways to create an instance of the class <eiffel>TIME</eiffel>: by choosing the time (make), by getting the time from the system (<eiffel>make_now</eiffel>), or by choosing the number of seconds elapsed from the origin (<eiffel>make_by_seconds</eiffel>). The arguments of <eiffel>make</eiffel> and <eiffel>make_by_seconds</eiffel> have to respect the range of a day (see preconditions).
====Origin and cyclic representation====
@@ -21,16 +21,16 @@ The origin is 0 hour 0 minute and 0 second. Notion of time is relative to a day
====Comparison====
Instances of [[ref:libraries/time/reference/time_chart|TIME ]] may be compared. Functions <, +, >, and >= are available. Function is_equal or ~ can be used to test object equality, while = will compare references.
Instances of [[ref:libraries/time/reference/time_chart|TIME ]] may be compared. Functions <, +, >, and >= are available. Function <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>) can be used to test object equality, while <eiffel>=</eiffel> will compare references.
====Measurement====
The duration linked to an instance of [[ref:libraries/time/reference/time_chart|TIME]] (attribute duration) is an instance of [[ref:libraries/time/reference/time_duration_chart|TIME_DURATION]] . It is the duration from the origin until the current time. The function seconds returns the number of seconds since the origin. This function may be useful to get the number of seconds between two events.The feature - creates an interval between two instances of <eiffel>TIME</eiffel>. The duration of this interval is given by the function duration. However, this duration is not canonical (See [[Duration|Duration]] for precisions). In <eiffel>TIME</eiffel>, the feature relative_duration returns the same duration, but more efficiently and also it is canonical.
The duration linked to an instance of [[ref:libraries/time/reference/time_chart|TIME]] (attribute <eiffel>duration</eiffel>) is an instance of [[ref:libraries/time/reference/time_duration_chart|TIME_DURATION]] . It is the duration from the origin until the current time. The function seconds returns the number of seconds since the origin. This function may be useful to get the number of seconds between two events.The feature - creates an interval between two instances of <eiffel>TIME</eiffel>. The duration of this interval is given by the function duration. However, this duration is not canonical (See [[Duration|Duration]] for precisions). In <eiffel>TIME</eiffel>, the feature <eiffel>relative_duration</eiffel> returns the same duration, but more efficiently and also it is canonical.
====Operations====
* Set directly hour, minute and second with set_hour, set_minute and set_second. Arguments must satisfy the rules of creation.
* Adding hours, minutes and seconds with features hour_add, minute_add and second_add. Features add and + take an instance of TIME_DURATION as an Page 3 argument and add it to the current time.
* Moving to the next or the previous hour, minute or second with features hour_forth, hour_back, minute_forth, minute_back, second_forth and second_back. It is faster to use these features rather than those above (hour_back <-> hour_add (-1)).
* Set directly <eiffel>hour</eiffel>, <eiffel>minute</eiffel>, and <eiffel>second</eiffel> with <eiffel>set_hour</eiffel>, <eiffel>set_minute</eiffel>, and <eiffel>set_second</eiffel>. Arguments must satisfy the rules of creation.
* Adding hours, minutes, and seconds with features <eiffel>hour_add</eiffel>, <eiffel>minute_add</eiffel>, and <eiffel>second_add</eiffel>. Features <eiffel>add</eiffel> and <eiffel>+</eiffel> take an instance of TIME_DURATION as an Page 3 argument and add it to the current time.
* Moving to the next or the previous hour, minute, or second with features <eiffel>hour_forth</eiffel>, <eiffel>hour_back</eiffel>, <eiffel>minute_forth</eiffel>, <eiffel>minute_back</eiffel>, <eiffel>second_forth</eiffel>, and <eiffel>second_back</eiffel>. It is faster to use these features rather than those above (e.g., <eiffel>hour_back</eiffel> will outperform <eiffel>hour_add (-1)</eiffel> ).
==DATE==
@@ -38,7 +38,7 @@ The duration linked to an instance of [[ref:libraries/time/reference/time_chart|
====Creation====
There are also three ways to create an instance of the class <eiffel>DATE</eiffel>: by choosing the date (make, make_month_day_year, make_day_month_year), by getting the date from the system (make_now), or by choosing the number of days elapsed from the origin (make_by_days). The arguments of each creation procedure have to respect the common range (See preconditions).
There are also three ways to create an instance of the class <eiffel>DATE</eiffel>: by choosing the date (<eiffel>make</eiffel>, <eiffel>make_month_day_year</eiffel>, <eiffel>make_day_month_year</eiffel>), by getting the date from the system (<eiffel>make_now</eiffel>), or by choosing the number of days elapsed from the origin (<eiffel>make_by_days</eiffel>). The arguments of each creation procedure have to respect the common range (See preconditions).
====Origin====
@@ -46,29 +46,29 @@ The origin is 01/01/1600.
====Comparison====
Instances of <eiffel>DATE</eiffel> may be compared. Functions <, +, >, and >= are available. Function is_equal or ~ can be used to test object equality, while = will compare references.
Instances of <eiffel>DATE</eiffel> may be compared. Functions <, +, >, and >= are available. Function <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>) can be used to test object equality, while <eiffel>=</eiffel> will compare references.
====Measurement====
Each instance of <eiffel>DATE</eiffel> has a function (duration) which returns the duration since the origin until the current date (it is an instance of DATE_DURATION). This duration is definite, i.e. it contains only days (See below). However, it may be useful to deal directly with days (no need of DATE_DURATION). In this case, the function days of <eiffel>DATE</eiffel> yields the number of days since origin.
Each instance of <eiffel>DATE</eiffel> has a function (<eiffel>duration</eiffel>) which returns the duration since the origin until the current date (it is an instance of DATE_DURATION). This duration is definite, i.e. it contains only days (See below). However, it may be useful to deal directly with days (no need of DATE_DURATION). In this case, the function <eiffel>days</eiffel> of <eiffel>DATE</eiffel> yields the number of days since origin.
====Status Report====
Much information may be gotten from functions written in this part. Most of them are used within the class, but they are exported at the same time.
You can obtain information about instances from status reporting functions. Most of these queries are used within the class, but they are also exported for use by clients.
====Operations====
<eiffel>DATE</eiffel> operations looks like <eiffel>TIME</eiffel> operations:
* Setting directly year, month and day with set_year, set_month, and set_day. Arguments must satisfy the rules of creation. These rules are more complicated than those of <eiffel>TIME</eiffel>. For example it is not allowed to set day to 31 if the current month is April, whereas it is allowed if the month is January. It is the same rules as for make. The same thing for years: It is not allowed to set year to a non-leap year if the current date is February 29th of a leap year. However, two features are available to set month and year even if day is too large: set_month_cut_days and set_year_cut_days will cut day down to the largest value allowed.
* Adding years, months and days with features year_add, month_add, and day_add. There is no requirement to add a year or a month. However, these features have to return a correct result, i.e. day is checked before each addition-. Adding one month to August 31st will yield September 30th. 31 is cut to 30 since there are only 30 days in September. Features add and + take an instance of DATE_DURATION in argument and add it to the current date. It is written so that years and months are added first, the days last.(see DATE_DURATION below)
* Moving to the next or the previous year, month or day with features year_forth, year_back, month_forth, month_back, day_forth, and day_back. It is the same but faster to use these features rather than those upper (year_back <-> year_add (-1)).
* Features relative_duration and definite_duration return the duration between the current date and the argument. The first one returns a result which is canonical (See definitions below), while the second one returns a definite result but may be not canonical.
* Setting directly <eiffel>year</eiffel>, <eiffel>month</eiffel>, and <eiffel>day</eiffel> with <eiffel>set_year</eiffel>, <eiffel>set_month</eiffel>, and <eiffel>set_day</eiffel>. Arguments must satisfy the rules of creation. These rules are more complicated than those of <eiffel>TIME</eiffel>. For example it is not allowed to set day to 31 if the current month is April, whereas it is allowed if the month is January. It is the same rules as for make. The same thing for years: It is not allowed to set year to a non-leap year if the current date is February 29th of a leap year. However, two features are available to set month and year even if day is too large: <eiffel>set_month_cut_days</eiffel> and <eiffel>set_year_cut_days</eiffel> will cut day down to the largest value allowed.
* Adding years, months and days with features <eiffel>year_add</eiffel>, <eiffel>month_add</eiffel>, and <eiffel>day_add</eiffel>. There is no requirement to add a year or a month. However, these features have to return a correct result, i.e. day is checked before each addition-. Adding one month to August 31st will yield September 30th. 31 is cut to 30 since there are only 30 days in September. Features <eiffel>add</eiffel> and <eiffel>+</eiffel> take an instance of DATE_DURATION in argument and add it to the current date. It is written so that years and months are added first, the days last.(see DATE_DURATION below)
* Moving to the next or the previous year, month or day with features <eiffel>year_forth</eiffel>, <eiffel>year_back</eiffel>, <eiffel>month_forth</eiffel>, <eiffel>month_back</eiffel>, <eiffel>day_forth</eiffel>, and <eiffel>day_back</eiffel>. It is the same but faster to use these features rather than those upper (e.g., <eiffel>year_back</eiffel> performs better than <eiffel>year_add (-1)</eiffel> ).
* Features <eiffel>relative_duration</eiffel> and <eiffel>definite_duration</eiffel> return the duration between the current date and the argument. The first one returns a result which is canonical (See definitions below), while the second one returns a definite result but may be not canonical.
For example, date1 is April 20th and date2 is May 28th. Both features will yield instances of DURATION; however, relative_duration will yield 1 month and 8 days whereas definite_duration will yield 38 days.
==DATE_TIME==
The aim is to gather the time with the date. <eiffel>DATE_TIME</eiffel> is client of <eiffel>TIME</eiffel> and <eiffel>DATE</eiffel> (see inheritance relation). Some features from <eiffel>DATE</eiffel> and <eiffel>TIME</eiffel> are re-written since they are useful within the class. Many other features may be called indirectly with the correct attribute (time or date).
The aim is to gather the time with the date. <eiffel>DATE_TIME</eiffel> is client of both <eiffel>TIME</eiffel> and <eiffel>DATE</eiffel> (see inheritance relation). Some features from <eiffel>DATE</eiffel> and <eiffel>TIME</eiffel> are re-written since they are useful within the class. Many other features may be called indirectly with the correct attribute (time or date).
====Creation====

68
documentation/current/solutions/dates-and-times/eiffeltime/eiffeltime-tutorial/duration.wiki
View File

@@ -3,9 +3,9 @@
[[Property:uuid|64672bd0-b696-0c39-1e30-5ac64aae4a99]]
<eiffel>TIME_DURATION</eiffel>, <eiffel>DATE_DURATION</eiffel>, and <eiffel>DATE_TIME_DURATION</eiffel>
The classes dealing with duration inherit DURATION, which inherits GROUP_ELEMENT and PART_COMPARABLE. An instance of <eiffel>TIME_DURATION</eiffel>, <eiffel>DATE_DURATION</eiffel>, or <eiffel>DATE_TIME_DURATION</eiffel> is an element of a group, i.e. there is a zero and addition operations (infix <eiffel>+</eiffel>, infix <eiffel>-</eiffel>, prefix <eiffel>+</eiffel>, and prefix <eiffel>-</eiffel>). Duration is used as an amount of time, without link to an origin. It may be added to the respective absolute notion (time + time_duration is possible, not time + date_time_duration nor date_time + time_duration...see classes <eiffel>TIME</eiffel>, <eiffel>DATE</eiffel>, and <eiffel>DATE_TIME</eiffel>).
The classes dealing with duration inherit DURATION, which inherits GROUP_ELEMENT and PART_COMPARABLE. An instance of <eiffel>TIME_DURATION</eiffel>, <eiffel>DATE_DURATION</eiffel>, or <eiffel>DATE_TIME_DURATION</eiffel> is an element of a group, i.e. there is a zero and addition operations (infix +, infix -, prefix +, and prefix -). Duration is used as an amount of time, without link to an origin. It may be added to the respective absolute notion (time + time_duration is possible, not time + date_time_duration nor date_time + time_duration...see classes <eiffel>TIME</eiffel>, <eiffel>DATE</eiffel>, and <eiffel>DATE_TIME</eiffel>).
Attributes are allowed to take negative values or values which do not stand in the usual range (<eiffel>hour = -1</eiffel>, <eiffel>minute = 75</eiffel>, <eiffel>day = 40</eiffel>...). However, features are available in each class to convert instances into the usual format: functions <eiffel>canonical</eiffel> and <eiffel>to_canonical</eiffel> are present in each class. An instance is canonical (<eiffel>canonical = True</eiffel>) if its attributes stand into the usual range. For example, an instance of <eiffel>TIME_DURATION</eiffel> such as 12:-10:60 is not canonical. to_canonical will return 11:51:0. In <eiffel>DATE_DURATION</eiffel> and <eiffel>DATE_TIME_DURATION</eiffel>, these features are also present.
Attributes are allowed to take negative values or values which do not stand in the usual range (hour = -1, minute = 75, day = 40...). However, features are available in each class to convert instances into the usual format: functions canonical and to_canonical are present in each class. An instance is canonical (canonical = True) if its attributes stand into the usual range. For example, an instance of <eiffel>TIME_DURATION</eiffel> such as 12:-10:60 is not canonical. to_canonical will return 11:51:0. In <eiffel>DATE_DURATION</eiffel> and <eiffel>DATE_TIME_DURATION</eiffel>, these features are also present.
The order is partially implemented. <eiffel>TIME_DURATION</eiffel> has a complete order whereas <eiffel>DATE_DURATION</eiffel> and <eiffel>DATE_TIME_DURATION</eiffel> are more specific.
@@ -13,49 +13,47 @@ The order is partially implemented. <eiffel>TIME_DURATION</eiffel> has a complet
====Creation====
Two ways are possible: by choosing the value of each attributes hour, minute and second (feature make), or by giving an amount of seconds (<eiffel>make_by_seconds</eiffel>). Any integer value is accepted. It is possible to create a duration with 1 hour and -60 minutes.
Two ways are possible: by choosing the value of each attributes hour, minute and second (feature make), or by giving an amount of seconds (make_by_seconds). Any integer value is accepted. It is possible to create a duration with 1 hour and -60 minutes.
====Access====
<eiffel>zero</eiffel> is a once feature with 0 hour, 0 minute and 0 second.
The total number of seconds in the current duration can be obtained by applying the feature <eiffel>seconds_count</eiffel>.
Zero is a once feature with 0 hour, 0 minute and 0 second. The total amount of second of the current duration is the result of feature seconds_count.
====Comparison====
Instances of <eiffel>TIME_DURATION</eiffel> may be compared easily. The order is the order oft he respective total amount of second. 1:-40:0 is less than 0:0:1800, etc... Functions <, >, <=, and >= are available. <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>) tests object equality, <eiffel>=</eiffel> will compare references.
Instances of <eiffel>TIME_DURATION</eiffel> may be compared easily. The order is the order oft he respective total amount of second. 1:-40:0 is less than 0:0:1800, etc... Functions <, >, <=, and >= are available. Is_equal tests equality, = will compare references.
====Element change====
Set directly <eiffel>hour</eiffel>, <eiffel>minute</eiffel>, and <eiffel>second</eiffel> with <eiffel>set_hour</eiffel>, <eiffel>set_minute</eiffel>, and <eiffel>set_second</eiffel>. Arguments do not need to satisfy any range rule.
Set directly hour, minute and second with set_hour, set_minute and set_second. Arguments do not need to satisfy any range rule.
====Operations====
* Adding hours, minutes and seconds with features <eiffel>hour_add</eiffel>, <eiffel>minute_add</eiffel> and <eiffel>second_add</eiffel>.
* <eiffel>TIME_DURATION</eiffel> inherits from GROUP_ELEMENT. infix and prefix <eiffel>+</eiffel>, infix and prefix <eiffel>-</eiffel> are available to compose instances of each other.
* Adding hours, minutes and seconds with features hour_add, minute_add and second_add.
* <eiffel>TIME_DURATION</eiffel> inherits from GROUP_ELEMENT. infix and prefix +, infix and prefix - are available to compose instances of each other.
====Conversion====
Two features ensure a link with the notion of day: <eiffel>to_days</eiffel> returns the number of days equivalent to the current duration. For example, a duration such as 23:60:0 is equivalent to one day. For negative duration, the result is never 0. -1 hour is equivalent to -1 day (i.e. the result of the function is -1). <eiffel>to_days</eiffel> is associated with <eiffel>time_modulo_day</eiffel>. This second function returns an instance of <eiffel>TIME_DURATION</eiffel>. The result represents the difference between the current duration and the number of days yielded by <eiffel>to_days</eiffel>. It implies that the result is always positive and less than one day.
Two features ensure a link with the notion of day: to_days returns the number of days equivalent to the current duration. For example, a duration such as 23:60:0 is equivalent to one day. For negative duration, the result is never 0. -1 hour is equivalent to -1 day (i.e. the result of the function is -1). To_days is associated with time_modulo_day. This second function returns an instance of <eiffel>TIME_DURATION</eiffel>. The result represents the difference between the current duration and the number of days yielded by to_days. It implies that the result is always positive and less than one day.
For example, the current duration is 25:70:600. <eiffel>to_days</eiffel> will return 1 (one day) and <eiffel>time_modulo_day</eiffel> will return 2:20:0:. If the current duration is negative: -23:-80:300, <eiffel>to_days</eiffel> will return -2 (minus two days) and <eiffel>time_modulo_day</eiffel> will return 23:45:0.
For example, the current duration is 25:70:600. to_days will returns 1 (one day) and time_modulo_day will return 2:20:0:. If the current duration is negative: -23:-80:300,to_days will return -2 (minus two days) and time_modulo_day will return 23:45:0.
Durations may be canonical or not canonical (<eiffel>BOOLEAN canonical</eiffel>). That means the features <eiffel>hour</eiffel>, <eiffel>minute</eiffel>, and <eiffel>second</eiffel> are included in a particular range, or not. An instance of <eiffel>TIME_DURATION</eiffel> is canonical if:
* in the case of a positive duration (> zero), all of the three features have to be positive or 0, <eiffel>minute</eiffel> and <eiffel>second</eiffel> less than 60.
* in the case of a negative duration (< zero), all of the three features have to be negative or 0, <eiffel>minute</eiffel> and <eiffel>second</eiffel> strictly greater than -60. The function <eiffel>canonical</eiffel> tests if the duration is canonical or not, the function <eiffel>to_canonical</eiffel> yields a new duration equivalent to the current one and canonical.
Durations may be canonical or not canonical (BOOLEAN canonical). That means the features hour, minute and second are included in a particular range, or not. An instance of <eiffel>TIME_DURATION</eiffel> is canonical if:
* in the case of a positive duration (> zero), all of the three features have to be positive or 0, minute and second less than 60.
* in the case of a negative duration (< zero), all of the three features have to be negative or 0, minute and second strictly greater than -60. The function canonical tests if the duration is canonical or not, the function to_canonical yields a new duration equivalent to the current one and canonical.
==DATE_DURATION==
Dealing with the Gregorian calendar is not so easy because of irregularities. A duration of one month may be equal to 28 up to 31 days, depending on the current date! On the other hand, it could be useful to deal with precise duration. This point leads to an original design of the class: A separation is made between two kinds of instances.
The definite ones and the relative ones. The function <eiffel>definite</eiffel> which returns a <eiffel>BOOLEAN</eiffel>, is true for definite duration and false otherwise. An instance is definite if and only if its attributes <eiffel>month</eiffel> and <eiffel>year</eiffel> are 0. Then only the number of days is used. Relative (non definite) durations have their attributes <eiffel>year</eiffel>, <eiffel>month</eiffel>, and <eiffel>day</eiffel> meaningful but it is then impossible to compare them to each other (is one month greater than 30 days?, is one year greater than 365 days?). The main difference appears when a duration is added to a date. In the case of a definite duration, there is no ambiguity. A given number of days are added to the date, taking care of the calendar. In the other case, the result is relative to the origin date. For example, a one month duration may be equal to 28 days if the date is in February or 31 days if the date is in August. A duration becomes definite when its attributes <eiffel>year</eiffel> and <eiffel>month</eiffel> become 0. However it is possible to deal with instances of <eiffel>DATE_DURATION</eiffel> without taking care of this distinction.
The definite ones and the relative ones. The function definite which returns a BOOLEAN, is true for definite duration and false otherwise. An instance is definite if and only if its attributes month and year are 0. Then only the number of days is used. Relative (non definite) durations have their attributes year, month and day meaningful but it is then impossible to compare them to each other (is one month greater than 30 days?, is one year greater than 365 days?). The main difference appears when a duration is added to a date. In the case of a definite duration, there is no ambiguity. A given number of days are added to the date, taking care of the calendar. In the other case, the result is relative to the origin date. For example, a one month duration may be equal to 28 days if the date is in February or 31 days if the date is in August. A duration becomes definite when its attributes year and month become 0. However it is possible to deal with instances of <eiffel>DATE_DURATION</eiffel> without taking care of this distinction.
===Relative date_duration===
Relative duration cannot be compared with any other durations (including zero). The reason is simple. It is not possible to say if 30 days are less than 1 month: it depends on the date: it is true in August (in a 31 days month) and it is false in February.
If feature <eiffel>></eiffel> (or <eiffel><</eiffel>) is called with at least one non definite member (the current instance or the argument), the result will be always False. We may only know if two durations have equal value with the feature <eiffel>is_equal</eiffel> (or <eiffel>~</eiffel>). It compares field by field the two durations. When adding a relative date_duration to a date, the years and the months are added first, then the date may be cut (June 31 -> June 30) and finally the days are added. For example, if one month is added to the date August 31st, the result is September 30th.
If feature > (or <, + + is called with at least one non definite member (the current instance or the argument), the result will be always False. We may only know if two durations are equal, with the feature is_equal. It compares field by field the two durations. When adding a relative date_duration to a date, the years and the months are added first, then the date may be cut (June 31 -> June 30) and finally the days are added. For example, if one month is added to the date August 31st, the result is September 30th.
Nevertheless, there is a way to compare relative durations: a relative date_duration may be canonical. It means that the duration has its attributes <eiffel>month</eiffel> and <eiffel>day</eiffel> in a fixed range. <eiffel>month</eiffel> must be between 1 and 12, and <eiffel>day</eiffel> larger than 1 and less than a value between 27 and 30. This value is fixed simply: (in the case of a positive duration) when setting day to 0 and adding one more month, the addition of the start date and this new duration must yield a date strictly after the final date (yielded by adding date and tested duration). For example is 0/0/30 (i.e. 0 year, 0 month and 30 days) canonical?
Nevertheless there is a way to compare relative durations: a relative date_duration may be canonical. It means that the duration has its attributes month and day in a fixed range.month must be between 1 and 12, and day larger than 1 and less than a value between 27 and 30. This value is fixed simply: (in the case of a positive duration) when setting day to 0 and adding one more month, the addition of the start date and this new duration must yield a date strictly after the final date (yielded by adding date and tested duration). For example is 0/0/30 (i.e. 0 year, 0 month and 30 days) canonical?
* If the origin date is 01/15 (15th of January), the final date is 02/14. We cannot convert 30 days into 1 month in this case. The duration is canonical.
* If the origin date is 04/15 (15th of April), the final date is 05/15. The duration is not canonical since it is possible to convert days into 1 month. The origin date is used to determine whether the duration is positive or not. If the final date is after the origin date the duration is positive, otherwise it is negative. That does not mean we can compare it to zero, that is only used to determine the sign of the canonical standard. If the duration is negative, it is canonical only if all the attributes are negative.
@@ -73,23 +71,23 @@ A definite duration may be canonical or not. It is canonical if the number of da
====Creation====
Two creation features are available: <eiffel>make</eiffel> takes three arguments (<eiffel>year</eiffel>, <eiffel>month</eiffel>, and <eiffel>day</eiffel>). If year and month are null, the duration will be definite; <eiffel>make_by_days</eiffel> takes only the number of day. The duration is automatically definite.
Two creation features are available: make takes three arguments (year, month and day). If year and month are null, the duration will be definite; make_by_days takes only the number of day. The duration is automatically definite.
====Comparison====
Features <, >, <=, and >= are available. If both instances are definite, numbers of days are compared. If one of them is non definite, the result is False.
Features <, >, <= and >= are available. If both instances are definite, numbers of days are compared. If one of them is non definite, the result is False.
====Element change====
Features <eiffel>set_day</eiffel>, <eiffel>set_month</eiffel>, and <eiffel>set_year</eiffel> are available to set one of these three attributes <eiffel>day</eiffel>, <eiffel>month</eiffel>, <eiffel>year</eiffel>.
Features set_day, set_month and set_year are available to set one of these three attributes day, month, year.
====Operation====
* Add years, months and days with features <eiffel>year_add</eiffel>, <eiffel>month_add</eiffel>, and <eiffel>day_add</eiffel>.
* <eiffel>DATE_DURATION</eiffel> inherits from GROUP_ELEMENT. infix and prefix <eiffel>+</eiffel>, infix and prefix <eiffel>-</eiffel> are available to compose instances of each other.
* Add years, months and days with features year_add, month_add and day_add.
* <eiffel>DATE_DURATION</eiffel> inherits from GROUP_ELEMENT. infix and prefix +, infix and prefix - are available to compose instances of each other.
====Conversion====
* <eiffel>to_canonical</eiffel> is used to get a new duration equivalent to the current one and canonical. It needs an argument from class <eiffel>DATE</eiffel>, which is the origin of calculations.
* <eiffel>to_definite</eiffel> is used to get a new duration equivalent to the current one and definite. As with the previous feature, one argument is needed. - <eiffel>to_date_time</eiffel> is used to get an instance of <eiffel>DATE_TIME_DURATION</eiffel>. It will have the same date of the current duration and time set to zero.
* to_canonical is used to get a new duration equivalent to the current one and canonical. It needs an argument from class <eiffel>DATE</eiffel>, which is the origin of calculations.
* to_definite is used to get a new duration equivalent to the current one and definite. As with the previous feature, one argument is needed. - to_date_time is used to get an instance of <eiffel>DATE_TIME_DURATION</eiffel>. It will have the same date of the current duration and time set to zero.
==DATE_TIME_DURATION==
@@ -100,29 +98,29 @@ There are, as in <eiffel>DATE_DURATION</eiffel>, definite and non definite durat
====Creation====
There are still several ways to create an instance:
* by choosing values for all the attributes of date and time (<eiffel>make</eiffel>). - by choosing a value for day and values for all the attributes of time. The instance is then definite (<eiffel>make_definite</eiffel>).
* by gathering an instance of <eiffel>DATE</eiffel> with an instance of <eiffel>TIME</eiffel> (<eiffel>make_by_date_time</eiffel>). This feature copies the references of its arguments, so that if the time (or the date) is changed, the instance previously initialized will be also changed. If this effect has to be avoided, the use of twins is required.
* by encapsulating an instance of <eiffel>DATE</eiffel> (<eiffel>make_by_date</eiffel>). The attribute <eiffel>time</eiffel> is set to zero, i.e. 0:0:0. The attribute <eiffel>date</eiffel> is set with the same reference than the argument.
* by choosing values for all the attributes of date and time (make). - by choosing a value for day and values for all the attributes of time. The instance is then definite (make_definite).
* by gathering an instance of <eiffel>DATE</eiffel> with an instance of <eiffel>TIME</eiffel> (make_by_date_time). This feature copies the references of its arguments, so that if the time (or the date) is changed, the instance previously initialized will be also changed. If this effect has to be avoided, the use of clones is required.
* by encapsulating an instance of <eiffel>DATE</eiffel> (make_by_date). The attribute time is set to zero, i.e. 0:0:0. The attribute date is set with the same reference than the argument.
====Access====
<eiffel>seconds_count</eiffel> is the amount of seconds of the time part only. To get the total amount of seconds of the current duration, first shift it to a definite duration, then multiply day by the number of seconds in day and add to it <eiffel>seconds_count</eiffel>. Take care that the duration is not more than 68 years. If it is, the number of seconds will be larger than 2 billion, which is the upper limit for INTEGER (4 bytes).
Seconds_count is the amount of seconds of the time part only. To get the total amount of seconds of the current duration, first shift it to a definite duration, then multiply day by the number of seconds in day and add to it seconds_count. Take care that the duration is not more than 68 years. If it is, the number of seconds will be larger than 2 billion, which is the upper limit for INTEGER (4 bytes).
====Comparison====
The rules are the same than those for <eiffel>DATE_DURATION</eiffel>. Features <, >,<=, and >= are available. If both instances are definite, numbers of days are compared. If one of them is non definite, the result is False.
The rules are the same than those for <eiffel>DATE_DURATION</eiffel>. Features <, >,<= and >= are available. If both instances are definite, numbers of days are compared. If one of them is non definite, the result is False.
====Element change====
It is possible to change reference of time and date with the features <eiffel>set_time</eiffel> and <eiffel>set_date</eiffel>. To change only one element (for example <eiffel>hour</eiffel>), features from <eiffel>TIME_DURATION</eiffel> or <eiffel>DATE_DURATION</eiffel>have to be used.
It is possible to change reference of time and date with the features set_time and set_date. To change only one element (for example hour), features from <eiffel>TIME_DURATION</eiffel> or <eiffel>DATE_DURATION</eiffel>have to be used.
====Operation====
* <eiffel>DATE_TIME_DURATION</eiffel> inherits from GROUP_ELEMENT. infix and prefix <eiffel>+</eiffel>, infix and prefix <eiffel>-</eiffel> are available to compose instances to each other.
* Only <eiffel>day_add</eiffel> is present. To add only one element, features from <eiffel>TIME_DURATION</eiffel> or <eiffel>DATE_DURATION</eiffel> have to be used.
* <eiffel>DATE_TIME_DURATION</eiffel> inherits from GROUP_ELEMENT. infix and prefix +, infix and prefix - are available to compose instances to each other.
* Only day_add is present. To add only one element, features from <eiffel>TIME_DURATION</eiffel> or <eiffel>DATE_DURATION</eiffel> have to be used.
====Conversion====
* <eiffel>canonical</eiffel> and <eiffel>to_canonical</eiffel> are available in the class. To be canonical an instance of the class must have its attributes <eiffel>time</eiffel> and <eiffel>date</eiffel> canonical. Then time must have the same sign than the one of the current duration. The sign of the current instance is determined by adding it to the argument (from <eiffel>DATE_TIME</eiffel>). That will yield a final date. If this final date is after the origin (= the argument), the current duration is considered positive. Otherwise, it is considered negative. Finally time must be less than one day (if positive) or more than minus one day (if negative). <eiffel>to_canonical</eiffel> returns a duration equivalent to the current one (for the argument) and canonical.
* <eiffel>time_to_canonical</eiffel> looks like <eiffel>to_canonical</eiffel> but focuses mainly on time. It requires a definite duration so that it is possible to compare it to zero. It yields a definite duration equivalent to the current one with a canonical time. <eiffel>hour</eiffel> is then cut so that it stands in the range of one day (0 to 23 if positive and -23 to 0 if negative). The attribute <eiffel>day</eiffel> is also modified to keep the result equivalent to the current duration. <eiffel>time_to_canonical</eiffel> does not need any argument because only time and day are modified.
* canonical and to_canonical are available in the class. To be canonical an instance of the class must have its attributes time and date canonical. Then time must have the same sign than the one of the current duration. The sign of the current instance is determined by adding it to the argument (from <eiffel>DATE_TIME</eiffel>). That will yield a final date. If this final date is after the origin (= the argument), the current duration is considered positive. Otherwise, it is considered negative. Finally time must be less than one day (if positive) or more than minus one day (if negative). To_canonical returns a duration equivalent to the current one (for the argument) and canonical.
* time_to_canonical looks like to_canonical but focuses mainly on time. It requires a definite duration so that it is possible to compare it to zero. It yields a definite duration equivalent to the current one with a canonical time. hour is then cut so that it stands in the range of one day (0 to 23 if positive and -23 to 0 if negative). The attributes day is also modified to keep the result equivalent to the current duration.time_to_canonical does not need any argument because only time and day are modified.

4
documentation/current/solutions/gui-building/eiffelbuild/eiffelbuild-reference/eiffelbuild-general-interface-description/eiffelbuild-window-overview.wiki
View File

@@ -8,9 +8,9 @@ The use of EiffelBuild is based around one main window which remains throughout
[[Image:main-window]]
The window contains several different tools, highlighted below:
* The [[Type selector|type selector]] - Situated at the top left of the window, this tool contains all the available vision2 types available for interface construction.
* The [[Type selector|type selector]] - Situated at the top left of the window, this tool contains all the available EiffelVision 2 types available for interface construction.
* The [[Component selector| component selector]] - Situated in the middle left of the window, below the [[Type selector|type selector]] , this tool contains all the user defined components.
* The [[Widget selector|widget selector]] - Situated in the bottom left of the window contains all of the EiffelVision2 windows contained in the open project. Each of these windows are generated by EiffelBuild as separate classes.
* The [[Widget selector|widget selector]] - Situated in the bottom left of the window contains all of the EiffelVision 2 windows contained in the open project. Each of these windows are generated by EiffelBuild as separate classes.
* The [[Layout constructor| layout constructor]] tool - Situated in the middle of the window, this tool displays a graphical representation of the interface that is currently being built.
* The docked [[Object editor|object editor]] - Situated to the right hand side of the window, this object editor automatically targets itself to the selected [[EiffelBuild Notation|object]] in the [[Layout constructor| layout constructor]] .

4
documentation/current/solutions/gui-building/eiffelbuild/eiffelbuild-reference/eiffelbuild-notation.wiki
View File

@@ -7,7 +7,7 @@ This page contains descriptions of terms found within the EiffelBuild documentat
An EiffelBuild object is a representation of a Vision2 component and its properties. When developing with EiffelBuild, you manipulate objects to build the desired interface.
Each object type has a different set of properties that may be manipulated, and these correspond directly to the properties available within the [[EiffelVision Introduction|EiffelVision2]] type. There is property which is specific to an EiffelBuild object, '''Name''' which is used for your identification purposes and as the attribute name in the generated code.
Each object type has a different set of properties that may be manipulated, and these correspond directly to the properties available within the [[EiffelVision Introduction|EiffelVision 2]] type. There is property which is specific to an EiffelBuild object, '''Name''' which is used for your identification purposes and as the attribute name in the generated code.
For more information on manipulating objects within EiffelBuild, see:
* How to [[Create an object|create an object]]
@@ -28,7 +28,7 @@ It is not possible to modify a component once created, except to [[Component sel
<span id="pick_and_drop"></span>
==Pick and Drop==
The pick and drop mechanism is one of Eiffel Software 's exclusive technologies and is provided by [[EiffelVision Introduction|EiffelVision2]] . In EiffelBuild, it allows you to easily send data from a component of the interface to another.
The pick and drop mechanism is one of Eiffel Software 's exclusive technologies and is provided by [[EiffelVision Introduction|EiffelVision 2]] . In EiffelBuild, it allows you to easily send data from a component of the interface to another.
You can '''Pick''' a reference to a '''development object''', such as an object or component with a single click of the '''right''' mouse button. Then as you start moving the mouse around - not pressing any of its buttons - a pebble tracks the cursor position, and a line continuously connects the pebble to the object's original position.

4
documentation/current/solutions/gui-building/eiffelbuild/eiffelbuild-reference/eiffelbuild-project-settings-window/build-tab.wiki
View File

@@ -15,7 +15,7 @@ The options available in this tab are as follows:
* <span id="build_type"></span> '''Build type'''
Select 'Project' if you wish to generate a complete project including an ace file, and an application class, which will launch the GUI you are developing.
Select `Class' if you wish to generate a single class that represents the GUI you are developing. This option is useful if you wish to incorporate your current project into an existing Vision2 system.
Select `Class' if you wish to generate a single class that represents the GUI you are developing. This option is useful if you wish to incorporate your current project into an existing EiffelVision 2 system.
* '''Always rebuild ace'''
This option causes the ace file to be completely re-generated every time you generate your project. If you do not wish the ace file to be re-generated, then disable this option. This check box is only available if 'build type' is set to 'project'.
@@ -24,7 +24,7 @@ This option causes the ace file to be completely re-generated every time you gen
This entry will be added to the generated ace file as the SYSTEM attribute. The executable built from compiling this ace file will have this name. This option is only available if you have specified 'build_type' as 'Project'.
* '''Application class name'''
This entry will be the class name for the generated vision2 application which will launch your GUI. This option is only available if you have specified 'build_type' as 'Project'.
This entry will be the class name for the generated EiffelVision 2 application which will launch your GUI. This option is only available if you have specified 'build_type' as 'Project'.
* '''Constants class name'''
This entry is used as the name of the constants class generated by EiffelBuild to define all [[Constants|constants]] contained in your project. Two classes are actually generated from this name, an implementation and an interface class. For example, if you specify a name "constants", two classes, <eiffel>CONSTANTS_IMP</eiffel> and <eiffel>CONSTANTS</eiffel> (inheriting from <eiffel>CONSTANTS_IMP</eiffel>) are generated, and all other classes generated by EiffelBuild, inherit <eiffel>CONSTANTS</eiffel> for access to these constants.

2
documentation/current/solutions/gui-building/eiffelvision-2/eiffelvision-2-samples/cursor-sample.wiki
View File

@@ -21,7 +21,7 @@ After launching the application, you will see a window displayed with a similar
To the right hand side of the window you will see an EV_MULTI_COLUMN_LIST containing rows, each with an associated EV_PIXMAP. If you select one of the rows of the list, then press the button marked "Apply", the cursor displayed when over the label displayed to the right hand side of the window will be pixmap of the currently selected list row.
==Under the Hood==
The pixmaps used in the EV_MULTI_COLUMN_LIST were standard pixmaps provided with vision2, accessible through EV_STOCK_PIXMAPS. set_pixmap was used to set the EV_PIXMAP of the EV_MULTI_COLUMN_LIST_ROW. An agent was added to the select_actions of the EV_BUTTON which calls set_pointer_style on the desired widget.
The pixmaps used in the EV_MULTI_COLUMN_LIST were standard pixmaps provided with EiffelVision 2, accessible through EV_STOCK_PIXMAPS. set_pixmap was used to set the EV_PIXMAP of the EV_MULTI_COLUMN_LIST_ROW. An agent was added to the select_actions of the EV_BUTTON which calls set_pointer_style on the desired widget.
This sample contains the following class:
* CURSOR_TEST

20
documentation/current/solutions/gui-building/eiffelvision-2/eiffelvision-introduction.wiki
View File

@@ -1,27 +1,27 @@
[[Property:title|EiffelVision Introduction]]
[[Property:weight|0]]
[[Property:uuid|f964651a-e36d-4e9e-00ea-37803a26373a]]
The EiffelVision 2 library offers an object-oriented framework for graphical user interface (GUI) development. Using EiffelVision 2, developers can access all necessary GUI components, called [[Widgets|widgets]] (buttons, windows, list views) as well as truly graphical elements such as points, lines, arcs, polygons and the like -- to develop a modern, functional and good-looking graphical interactive application.
The EiffelVision library offers an object-oriented framework for graphical user interface (GUI) development. Using EiffelVision, developers can access all necessary GUI components, called [[Widgets|widgets]] (buttons, windows, list views) as well as truly graphical elements such as points, lines, arcs, polygons and the like -- to develop a modern, functional and good-looking graphical interactive application.
EiffelVision 2 has played a major role at Eiffel Software and provided numerous Eiffel projects with a powerful, portable graphics development platform. EiffelStudio is totally reliant on EiffelVision 2 for its graphical elements and overall interaction with the user.
EiffelVision has played a major role at Eiffel Software and provided numerous Eiffel projects with a powerful, portable graphics development platform. EiffelStudio is totally reliant on EiffelVision for its graphical elements and overall interaction with the user.
==Scope==
The EiffelVision 2 library addresses all the major needs of developers of systems supporting modern graphical interfaces. EiffelVision 2 runs on Microsoft Windows and all major variations of Unix (including Linux). All versions are fully source-compatible; with only a recompile, applications will run on every supported platform with the native look-and-feel.
The EiffelVision library addresses all the major needs of developers of systems supporting modern graphical interfaces. EiffelVision runs on Microsoft Windows and all major variations of Unix (including Linux). All versions are fully source-compatible; with only a recompile, applications will run on every supported platform with the native look-and-feel.
EiffelVision 2 provides an effective way of building advanced graphical applications using user interface standards and toolkits (such as Microsoft Windows and GTK) without having to learn the details of the toolkits. Instead, you can use EiffelVision 2 to work entirely in terms of high level abstractions representing windows, buttons, labels, graphical figures, menus, buttons etc., and apply clearly understandable operations to the corresponding objects.
EiffelVision provides an effective way of building advanced graphical applications using user interface standards and toolkits (such as Microsoft Windows and GTK) without having to learn the details of the toolkits. Instead, you can use EiffelVision to work entirely in terms of high level abstractions representing windows, buttons, labels, graphical figures, menus, buttons etc., and apply clearly understandable operations to the corresponding objects.
==Architecture==
EiffelVision 2 relies on a two-tiered architecture illustrated by the following figure.
EiffelVision relies on a two-tiered architecture illustrated by the following figure.
[[Image:vision2--figure1]]
The two tiers play complementary roles:
* At the top level, EiffelVision 2 provides fully portable graphics.
* At the top level, EiffelVision provides fully portable graphics.
* At the lower level, platform-specific libraries cover the graphical mechanisms of graphics platforms such as Windows and GTK.
The lower tier serves for the implementation of the upper tier, but can also be used independently. For example [[WEL]] has had a resounding success with Windows developers who need an advanced mechanism for building Windows-specific graphical applications, taking advantage of every facility of the Windows API (Application Programming Interface) and of the Eiffel approach, but do not need portability on the client side. The GEL library is a '''wrapper''' library, automatically generated from the entire GTK API by a tool named '''The Gote Converter'''.
@@ -35,11 +35,11 @@ As stated before, the library has undergone some drastic changes since the previ
==Design==
EiffelVision 2 provides programmers with high-level classes, that provide all mechanism and data structures needed to build advanced user interfaces for deployment on almost all platforms without having to worry about detailed requirements of toolkits.
EiffelVision provides programmers with high-level classes, that provide all mechanism and data structures needed to build advanced user interfaces for deployment on almost all platforms without having to worry about detailed requirements of toolkits.
The abstract design has been derived from an analysis of user interfaces. Therefore we have classes with names like MENU, WINDOW, BUTTON, LINE or POLYGON. The features of these classes are simple, clearly defined properties or commands, like the feature `minimize' (a command) on WINDOW or `text' (a property of type STRING) on BUTTON.
{{note| All class names in EiffelVision 2 are pre-pended with EV_ to avoid name clashes with existing classes. BUTTON hence becomes <eiffel>EV_BUTTON</eiffel>, etc. }}
{{note| All class names in EiffelVision are pre-pended with EV_ to avoid name clashes with existing classes. BUTTON hence becomes <eiffel>EV_BUTTON</eiffel>, etc. }}
==Properties==
@@ -48,7 +48,7 @@ When talking about a property of a class, like `text', in fact we are talking ab
text: STRING
set_text (a_text: STRING)
...
...
do
...
end
@@ -74,7 +74,7 @@ Boolean properties have a different convention. Instead of one set-routine, it h
==Implementation==
For flexibility, EiffelVision 2 is built using the bridge pattern. This means that every platform-dependent component of the library consist of two classes, plus an implementation class for each platform (currently two). One is the <eiffel>interface</eiffel>. All the features of interfaces do nothing except delegate the call to the implementation object which is coupled to it. This object has the static type of the implementation-interface with the name of the interface class, with <eiffel>_I</eiffel> appended to it. From this implementation-interface, implementation classes inherit to implement platform-specific features.
For flexibility, EiffelVision is built using the bridge pattern. This means that every platform-dependent component of the library consist of two classes, plus an implementation class for each platform (currently two). One is the <eiffel>interface</eiffel>. All the features of interfaces do nothing except delegate the call to the implementation object which is coupled to it. This object has the static type of the implementation-interface with the name of the interface class, with <eiffel>_I</eiffel> appended to it. From this implementation-interface, implementation classes inherit to implement platform-specific features.

4
documentation/current/solutions/gui-building/eiffelvision-2/eiffelvision-library-reference-manual/index.wiki
View File

@@ -3,8 +3,8 @@
[[Property:uuid|b343b38b-c8b2-4247-072d-ecc1bc3e387a]]
EiffelVision 2 is a platform independent Graphical User Interface (GUI) library that allows easy, simultaneous development of Windowed applications for both Windows & Unix based platforms. Heavily relying on EiffelBase library, EiffelVision 2 has been designed primarily with ease of use in mind. By reusing EiffelBase structures, existing, as well as new Eiffel users will find EiffelVision to be surprising intuitive and easy to use. In no time, users will be producing good-looking Windowed application skeletons, of which will run on a multitude of platforms with no manipulation of code.
The EiffelVision 2 library includes the following interface clusters:
* A [[Kernel| kernel]] cluster that includes classes that are key to a Vision2 application. The main class being [[ref:libraries/vision2/reference/ev_application_chart| EV_APPLICATION]] which is the main entry point of all Vision2 applications.
* A [[Widgets| widgets]] cluster containing classes that used to create Vision2 widgets. Widgets are the visible objects that the user sees and interacts with on the desktop, examples of widgets are windows, buttons and labels.
* A [[Kernel| kernel]] cluster that includes classes that are key to a EiffelVision 2 application. The main class being [[ref:libraries/vision2/reference/ev_application_chart| EV_APPLICATION]] which is the main entry point of all EiffelVision 2 applications.
* A [[Widgets| widgets]] cluster containing classes that used to create EiffelVision 2 widgets. Widgets are the visible objects that the user sees and interacts with on the desktop, examples of widgets are windows, buttons and labels.
* An [[Items| items]] cluster includes the classes needed to create items, items can be thought of as widgets that are contained within only a certain type of widget, such as an [[ref:libraries/vision2/reference/ev_list_chart| EV_LIST]] that may only contain objects of type [[ref:libraries/vision2/reference/ev_list_item_chart|EV_LIST_ITEM]] . Items provide an abstract way of dealing with an item widget's internal data structures and provide in many cases the same functionality that a widget does.
* An [[Events| events]] cluster containing classes that allow for user initiated events, such as the clicking of a button to be dealt with via the use of a linked list of agents ( [[ref:libraries/vision2/reference/ev_action_sequence_chart|EV_ACTION_SEQUENCE]] ). Agents can be thought of as an object that encapsulates a certain procedure. When a user clicks a button on the screen, the corresponding [[ref:libraries/vision2/reference/ev_button_chart| EV_BUTTON]] object has its associating pointer_button_press_actions fired and this in turn, fires all of the agents held within, thus calling all of the procedures represented by the agents. Every widget and item has a certain number of [[ref:libraries/base/reference/action_sequence_chart|ACTION_SEQUENCE]] objects that are linked with a certain type of event.
* A [[Properties| properties]] cluster contains classes that allow for the customization of Vision 2 widgets and items. Classes such as [[ref:libraries/vision2/reference/ev_colorizable_chart|EV_COLORIZABLE]] and [[ref:libraries/vision2/reference/ev_fontable_chart|EV_FONTABLE]] contain routines that allow for color and fonts to be altered for a widget or item respectively.

98
documentation/current/solutions/gui-building/eiffelvision-2/eiffelvision-library-reference-manual/kernel.wiki
View File

@@ -1,77 +1,77 @@
[[Property:title|Kernel]]
[[Property:weight|1]]
[[Property:uuid|d830dc77-cd77-1f52-0e39-e0ec1cffa028]]
The kernel cluster contains classes that provide functionality that are common to most Windowed application. These classes are considered the core, or kernel of any EiffelVision2 application. The most important of these classes is [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] . This is used to initialize the graphical toolkit and event loop of your EiffelVision2 application. Kernel also includes classes such as [[ref:libraries/vision2/reference/ev_timeout_chart| EV_TIMEOUT]] that calls procedures (via agents) at a set interval, and [[ref:libraries/vision2/reference/ev_color_chart| EV_COLOR]] which is used for coloring widgets and items. To start programming with EiffelVision2, you first have to correctly initialize [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] .
The kernel cluster contains classes that provide functionality that are common to most Windowed application. These classes are considered the core, or kernel of any EiffelVision 2 application. The most important of these classes is [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] . This is used to initialize the graphical toolkit and event loop of your EiffelVision 2 application. Kernel also includes classes such as [[ref:libraries/vision2/reference/ev_timeout_chart| EV_TIMEOUT]] that calls procedures (via agents) at a set interval, and [[ref:libraries/vision2/reference/ev_color_chart| EV_COLOR]] which is used for coloring widgets and items. To start programming with EiffelVision 2, you first have to correctly initialize [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] .
==Launching your application with EV_APPLICATION - The heart of all Vision2 systems==
==Launching your application with EV_APPLICATION - The heart of all EiffelVision 2 systems==
[[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] is the basis for every EiffelVision2 application and is considered the most important class in the library. It is responsible for initializing the underlying toolkit that is driving the windowing system on the platform that you decide to compile your system on. It also also where the main event loop that drives your application is executed.
[[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] is the basis for every EiffelVision 2 application and is considered the most important class in the library. It is responsible for initializing the underlying toolkit that is driving the windowing system on the platform that you decide to compile your system on. It also also where the main event loop that drives your application is executed.
{{note|It is ''' not''' possible to create a Vision2 component unless an application exists (query [[ref:/libraries/vision2/reference/ev_environment_chart|EV_ENVIRONMENT]] ). }}
You may inherit [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] or use it as a client in order to create your EiffelVision2 application. A simple method of using EV_APPLICATION is as follows:
{{note|It is ''' not''' possible to create a EiffelVision 2 component unless an application exists (query [[ref:/libraries/vision2/reference/ev_environment_chart|EV_ENVIRONMENT]] ). }}
You may inherit [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] or use it as a client in order to create your EiffelVision 2 application. A simple method of using EV_APPLICATION is as follows:
# Create an instance of EV_APPLICATION.
# Create one or more windows for your application.
# Launch the application.
An example of an EiffelVision2 application using inheritance from [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] is shown below.
An example of an EiffelVision 2 application using inheritance from [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] is shown below.
<code>
class
HELLOWORLD_APP
class
HELLOWORLD_APP
inherit
EV_APPLICATION
inherit
EV_APPLICATION
create
make
create
make
feature
feature
make is
-- Create the application.
local
helloworld_window: EV_TITLED_WINDOW
do
default_create
create helloworld_window
helloworld_window.set_title ("Helloworld!")
helloworld_window.close_request_actions.extend (agent destroy)
helloworld_window.show
launch
end
make
-- Create the application.
local
helloworld_window: EV_TITLED_WINDOW
do
default_create
create helloworld_window
helloworld_window.set_title ("Helloworld!")
helloworld_window.close_request_actions.extend (agent destroy)
helloworld_window.show
launch
end
end
end
</code>
This is the same EiffelVision2 application but instead using [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] in a client/supplier relationship.
This is the same EiffelVision 2 application but instead using [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] in a client/supplier relationship.
<code>
class
HELLOWORLD_APP
class
HELLOWORLD_APP
create
make
create
make
feature
feature
make is
-- Create the EiffelVision2 application with a helloworld window.
local
app: EV_APPLICATION
helloworld_window: EV_TITLED_WINDOW
do
create app
create helloworld_window
helloworld_window.set_title ("Helloworld!")
helloworld_window.close_request_actions.extend (agent app.destroy)
helloworld_window.show
app.launch
end
make
-- Create the EiffelVision 2 application with a helloworld window.
local
app: EV_APPLICATION
helloworld_window: EV_TITLED_WINDOW
do
create app
create helloworld_window
helloworld_window.set_title ("Helloworld!")
helloworld_window.close_request_actions.extend (agent app.destroy)
helloworld_window.show
app.launch
end
end
end
</code>
==What does Launch actually do?==
In EiffelVision2, to launch an application means to pass control to the underlying graphical toolkit. Simply creating an application does not launch it. An explicit call to launch is required for the event processing to begin.
{{note|An EiffelVision2 system is event based. This means that you do not have control of the execution within an EiffelVision2 system, but must respond appropriately to [[Events|events]] as they occur. Therefore, if you call launch on an [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] , the processing for the application will continue indefinitely unless you have provided a way to exit the application. It is essential to initialize your components correctly, so your application can be exited (call <eiffel>destroy</eiffel> on the application). }}
In EiffelVision 2, to launch an application means to pass control to the underlying graphical toolkit. Simply creating an application does not launch it. An explicit call to launch is required for the event processing to begin.
{{note|An EiffelVision 2 system is event based. This means that you do not have control of the execution within an EiffelVision 2 system, but must respond appropriately to [[Events|events]] as they occur. Therefore, if you call launch on an [[ref:libraries/vision2/reference/ev_application_chart|EV_APPLICATION]] , the processing for the application will continue indefinitely unless you have provided a way to exit the application. It is essential to initialize your components correctly, so your application can be exited (call <eiffel>destroy</eiffel> on the application). }}
==Building your application skeleton==
@@ -80,5 +80,5 @@ Now that you have a basic application skeleton set up you can now go about
* [[Containers|Adding containers to your window(s), then place your created widgets in those containers.]]
* [[Events|Add code to respond to user actions with agents and action sequences.]]
Once you have learnt the basics of GUI programming within EiffelVision2, you are well on the way to creating powerful multi-platform applications. The Application Programming Interface (API) of EiffelVision2 has been designed in a way to ensure that the library is as intuitive, consistent and stylistic as possible. Heavy reuse of components from EiffelBase has been one of the main reasons that made this possible.
Once you have learnt the basics of GUI programming within EiffelVision 2, you are well on the way to creating powerful multi-platform applications. The Application Programming Interface (API) of EiffelVision 2 has been designed in a way to ensure that the library is as intuitive, consistent and stylistic as possible. Heavy reuse of components from EiffelBase has been one of the main reasons that made this possible.

18
documentation/current/solutions/gui-building/eiffelvision-2/eiffelvision-library-reference-manual/properties/eiffelvision-pick-and-drop.wiki
View File

@@ -1,11 +1,11 @@
[[Property:title|EiffelVision Pick and Drop]]
[[Property:weight|0]]
[[Property:uuid|309203de-6536-fe26-4f73-cb1f4a450e6f]]
Pick and drop is a mechanism which allows data to be transported from a '''source''' object to a '''target'''. Any Vision2 object inheriting [[ref:libraries/vision2/reference/ev_pick_and_dropable_chart|EV_PICK_AND_DROPABLE]] can be used to transport or receive data.
Pick and drop is a mechanism which allows data to be transported from a '''source''' object to a '''target'''. Any EiffelVision 2 object inheriting [[ref:libraries/vision2/reference/ev_pick_and_dropable_chart|EV_PICK_AND_DROPABLE]] can be used to transport or receive data.
==A simple pick and drop example==
Two necessary components for a pick and drop transport are a '''source''' and a '''target''', both of which must conform to [[ref:libraries/vision2/reference/ev_pick_and_dropable_chart|EV_PICK_AND_DROPABLE]] . The data that is to be transported is known as a '''pebble'''.
Two necessary components for a pick and drop transport are a '''source''' and a '''target''', both of which must conform to [[ref:libraries/vision2/reference/ev_pick_and_dropable_chart|EV_PICK_AND_DROPABLE]]. The data that is to be transported is known as a '''pebble'''.
The following steps need to be undertaken to set up a simple pick and drop:
* Set the '''source''' by calling set_pebble.
@@ -13,11 +13,11 @@ The following steps need to be undertaken to set up a simple pick and drop:
A simple example of this is demonstrated here:
<code>
button1.set_pebble ("A PND transport has occured%N")
button2.drop_actions.extend (agent print (?))
button1.set_pebble ("A PND transport has occured%N")
button2.drop_actions.extend (agent print (?))
</code>
As print takes an argument of type [[ref:/libraries/base/reference/string_8_chart|STRING_8]] , button2 becomes a valid target for the pebble contained in button1. Right clicking the mouse pointer over the '''source''' will start the transport, and right clicking with the mouse pointer over a valid '''target''' will end the transport. The transport can be canceled anytime with a simple left click, just as you would do in EiffelStudio.
As print takes an argument of type [[ref:/libraries/base/reference/string_8_chart|STRING_8]], button2 becomes a valid target for the pebble contained in button1. Right clicking the mouse pointer over the '''source''' will start the transport, and right clicking with the mouse pointer over a valid '''target''' will end the transport. The transport can be canceled anytime with a simple left click, just as you would do in EiffelStudio.
{{note|When a transport completes, the '''pebble''' that was transported is passed as an argument to all features in the '''targets''' drop_actions whose argument type matches the '''pebble'''. }}
@@ -25,14 +25,14 @@ As print takes an argument of type [[ref:/libraries/base/reference/string_8_char
There are three different modes of transport available for pick and drop. They are listed below with details of their use:
* Pick and Drop mode. <br/>
This is the default mode for pick and drop, but can be set with <eiffel>set_pick_and_drop_mode</eiffel>. Right clicking on a '''source''' starts the transport and right clicking on a valid '''target''' completes the transport. During execution, a band is drawn from the screen position where the pick started to the current mouse position. Pressing the left mouse button or the escape key during execution will end the transport.
:This is the default mode for pick and drop, but can be set with <eiffel>set_pick_and_drop_mode</eiffel>. Right clicking on a '''source''' starts the transport and right clicking on a valid '''target''' completes the transport. During execution, a band is drawn from the screen position where the pick started to the current mouse position. Pressing the left mouse button or the escape key during execution will end the transport.
* Drag and drop mode <br/>
This mode can be set with <eiffel>set_drag_and_drop_mode</eiffel>. Left clicking on a '''source''' starts the transport and releasing the left mouse button over a valid '''target''' completes the transport. During execution, a band is drawn from the screen position where the pick started to the current mouse position. Releasing the left mouse button or pressing the escape key during execution will end the transport.
:This mode can be set with <eiffel>set_drag_and_drop_mode</eiffel>. Left clicking on a '''source''' starts the transport and releasing the left mouse button over a valid '''target''' completes the transport. During execution, a band is drawn from the screen position where the pick started to the current mouse position. Releasing the left mouse button or pressing the escape key during execution will end the transport.
* Target menu mode <br/>
This mode can be set with <eiffel>set_target_menu_mode</eiffel>. Right clicking on a '''source''' brings up a menu of all the valid drop '''targets''' in the system. Selecting one of these targets completes the transport.
:This mode can be set with <eiffel>set_target_menu_mode</eiffel>. Right clicking on a '''source''' brings up a menu of all the valid drop '''targets''' in the system. Selecting one of these targets completes the transport.
==Accept and deny cursors==
When <eiffel>mode_is_pick_and_drop</eiffel> or <eiffel> mode_is_drag_and_drop</eiffel> then the shape of the mouse cursor changes to reflect whether the current GUI component below the mouse accepts the pebble or not. Calling <eiffel>set_accept_cursor</eiffel> allows you to customize this cursor used to represent a valid '''target''' while calling <eiffel>set_deny_cursor</eiffel> allows you to customize the cursor used for non valid '''targets'''.
When <eiffel>mode_is_pick_and_drop</eiffel> or <eiffel>mode_is_drag_and_drop</eiffel> then the shape of the mouse cursor changes to reflect whether the current GUI component below the mouse accepts the pebble or not. Calling <eiffel>set_accept_cursor</eiffel> allows you to customize this cursor used to represent a valid '''target''' while calling <eiffel>set_deny_cursor</eiffel> allows you to customize the cursor used for non valid '''targets'''.

32
documentation/current/solutions/gui-building/eiffelvision-2/eiffelvision-library-reference-manual/widgets/containers.wiki
View File

@@ -23,22 +23,22 @@ For example, [[ref:libraries/vision2/reference/ev_container_chart|EV_CONTAINER]]
The main role of a container is to position its children in a certain way. An [[ref:libraries/vision2/reference/ev_horizontal_box_chart| EV_HORIZONTAL_BOX]] for example positions its children side by side along the horizontal axis. To achieve vertical stacking you would use an [[ref:libraries/vision2/reference/ev_vertical_box_chart| EV_VERTICAL_BOX]] .
A code example of adding widgets to a container is as follows:
<code>
add_to_container is
-- Add 3 buttons to a hbox and then show in window.
local
a_window: EV_TITLED_WINDOW
a_hbox: EV_HORIZONTAL_BOX
a_button: EV_BUTTON
do
create a_window
create a_hbox
create a_button.make_with_text ("Button1")
a_hbox.extend (a_button)
a_hbox.extend (create {EV_BUTTON}.make_with_text ("Button2"))
a_hbox.extend (create {EV_BUTTON}.make_with_text ("Button3"))
a_window.extend (a_hbox)
a_window.show
end
add_to_container is
-- Add 3 buttons to a hbox and then show in window.
local
a_window: EV_TITLED_WINDOW
a_hbox: EV_HORIZONTAL_BOX
a_button: EV_BUTTON
do
create a_window
create a_hbox
create a_button.make_with_text ("Button1")
a_hbox.extend (a_button)
a_hbox.extend (create {EV_BUTTON}.make_with_text ("Button2"))
a_hbox.extend (create {EV_BUTTON}.make_with_text ("Button3"))
a_window.extend (a_hbox)
a_window.show
end
</code>
The mapping of a EiffelVision 2 container interface is very close to that of containers in [[EiffelBase]], such as a linked list.

4
documentation/current/solutions/gui-building/eiffelvision-2/eiffelvision-library-reference-manual/widgets/eiffelvision-dialogs.wiki
View File

@@ -1,11 +1,11 @@
[[Property:title|EiffelVision Dialogs]]
[[Property:weight|2]]
[[Property:uuid|85cfcfd3-a46e-4e2e-330a-61c2d1579b0f]]
This cluster contains all the dialogs provided by Vision2.
This cluster contains all the dialogs provided by EiffelVision 2.
==Standard dialogs==
A standard dialog provides a way of interacting with the underlying platform (such as Windows or Linux) to perform basic tasks such as opening a file or printing a document. Vision2 provides six dialogs that allow the user to perform everyday tasks that are
A standard dialog provides a way of interacting with the underlying platform (such as Windows or Linux) to perform basic tasks such as opening a file or printing a document. EiffelVision 2 provides six dialogs that allow the user to perform everyday tasks that are
* [[ref:libraries/vision2/reference/ev_color_dialog_chart|EV_COLOR_DIALOG]] -- This allows the user of your app to select an RGB color (useful for graphical apps such as a Paint Program).
* [[ref:libraries/vision2/reference/ev_directory_dialog_chart|EV_DIRECTORY_DIALOG]] -- This allows the user of your app to select a directory.
* [[ref:libraries/vision2/reference/ev_file_open_dialog_chart|EV_FILE_OPEN_DIALOG]] -- This allows the user of your app to select a file to be opened.

20
documentation/current/solutions/gui-building/eiffelvision-2/eiffelvision-library-reference-manual/widgets/index.wiki
View File

@@ -3,31 +3,31 @@
[[Property:uuid|595bb73e-146a-ea19-221f-40f3415aad34]]
==What is a Widget?==
A Widget is the fundamental building block of your applications GUI, components such as Windows, Buttons and Labels are examples of such. The widget set of Vision2 provides you with the flexibility to easily create powerful graphical applications. All widgets in Vision2 inherit from [[ref:/libraries/vision2/reference/ev_widget_chart| EV_WIDGET]] and the features provided in <eiffel> EV_WIDGET</eiffel> may be called on any widget.
A Widget is the fundamental building block of your applications GUI, components such as Windows, Buttons and Labels are examples of such. The widget set of EiffelVision 2 provides you with the flexibility to easily create powerful graphical applications. All widgets in EiffelVision 2 inherit from [[ref:/libraries/vision2/reference/ev_widget_chart| EV_WIDGET]] and the features provided in <eiffel>EV_WIDGET</eiffel> may be called on any widget.
==Variations of Widget==
Within Vision2, widgets have been classified into three different groups:
Within EiffelVision 2, widgets have been classified into three different groups:
* [[Primitives|Primitives]] -- These are elements of the user interface that are mainly responsible for interaction with the user, such as an [[ref:/libraries/vision2/reference/ev_button_chart|EV_BUTTON]] .
* [[Containers|Containers]] -- These are used to contain other widgets and position them in a certain way, such as an [[ref:/libraries/vision2/reference/ev_vertical_box_chart| EV_VERTICAL_BOX ]] that stacks its children one by one vertically.
* [[EiffelVision Dialogs|Dialogs]] -- These are pop up dialog windows used for interacting with the user for tasks such as opening a file (EV_FILE_OPEN_DIALOG) or displaying a message (EV_MESSAGE_DIALOG). You may construct your own dialogs by inheriting EV_DIALOG.
==How do I create a widget?==
All widgets in Vision2 are based around the default_create mechanism in Eiffel. This means that all that needs to be done to create a widget is to declare a reference to a type (such as [[ref:libraries/vision2/reference/ev_button_chart|EV_BUTTON]] ) and then call create on that reference. An example of this is as follows.
All widgets in EiffelVision 2 are based around the default_create mechanism in Eiffel. This means that all that needs to be done to create a widget is to declare a reference to a type (such as [[ref:libraries/vision2/reference/ev_button_chart|EV_BUTTON]] ) and then call create on that reference. An example of this is as follows.
<code>
a_button: EV_BUTTON
create a_button
a_button: EV_BUTTON
create a_button
</code>
Along with the default creation, Vision2 also includes a few convenience creation functions. Examples of this are make_with_text for all widgets that may have text associated with them (those that inherit from [[ref:libraries/vision2/reference/ev_textable_chart| EV_TEXTABLE]] ), this saves a call to set_text upon default creation of the textable widget.
Along with the default creation, EiffelVision 2 also includes a few convenience creation functions. Examples of this are make_with_text for all widgets that may have text associated with them (those that inherit from [[ref:libraries/vision2/reference/ev_textable_chart| EV_TEXTABLE]] ), this saves a call to set_text upon default creation of the textable widget.
<code>
create a_button.make_with_text ("Click Me")
create a_button.make_with_text ("Click Me")
</code>
This would be in place of
<code>
create a_button
a_button.set_text ("Click Me")
create a_button
a_button.set_text ("Click Me")
</code>
{{note|When a widget is created no extra initialization has to be performed. '''The only exception is for a window where you have to call show in order for it to be displayed on screen'''. }}
@@ -38,7 +38,7 @@ As [[ref:libraries/vision2/reference/ev_primitive_chart|EV_PRIMITIVE]] is of ty
The minimum size of a widget is the smallest possible size that it can possibly be inside its parent container. If an [[ref:libraries/vision2/reference/ev_button_chart|EV_BUTTON]] was created and set with a minimum_size of width/height (100, 100), if this button was inserted in to an [[ref:libraries/vision2/reference/ev_horizontal_box_chart| EV_HORIZONTAL_BOX]] , then the box's size could never be below (100, 100) or it would break the minimum size of the button. '''The size of a container must always be greater or equal to the minimum sizes of its children.'''
{{note|In Vision2, there is no way to set the current size of the primitive. The current size is dependent on the size of the parent or the minimum_size. }}
{{note|In EiffelVision 2, there is no way to set the current size of the primitive. The current size is dependent on the size of the parent or the minimum_size. }}
==Now what do I do?==
Now that you can create a widget, you will need to actually make it usable to your intended user. This will usually involve these three steps. <br/>

4
documentation/current/solutions/gui-building/eiffelvision-2/eiffelvision-library-reference-manual/widgets/primitives.wiki
View File

@@ -1,10 +1,10 @@
[[Property:title|Primitives]]
[[Property:weight|0]]
[[Property:uuid|09d70dd5-2e30-7615-88ac-4babe4eb7aa6]]
All Vision2 primitives inherit [[ref:libraries/vision2/reference/ev_primitive_chart|EV_PRIMITIVE]] .
All EiffelVision 2 primitives inherit [[ref:libraries/vision2/reference/ev_primitive_chart|EV_PRIMITIVE]] .
==What is a primitive?==
A primitive is a Vision2 widget that may not contain other widgets. Primitives may be placed in [[Containers|containers]] , but a [[Widgets|widget ]] may not contain any child widgets. Some examples of primitives are [[ref:libraries/vision2/reference/ev_button_chart|EV_BUTTON]] and [[ref:libraries/vision2/reference/ev_label_chart|EV_LABEL]] .
A primitive is a EiffelVision 2 widget that may not contain other widgets. Primitives may be placed in [[Containers|containers]] , but a [[Widgets|widget ]] may not contain any child widgets. Some examples of primitives are [[ref:libraries/vision2/reference/ev_button_chart|EV_BUTTON]] and [[ref:libraries/vision2/reference/ev_label_chart|EV_LABEL]] .
==Features of a primitive==
All primitives inherit from [[ref:libraries/vision2/reference/ev_tooltipable_chart|EV_TOOLTIPABLE]] and therefore can have tooltips assigned to them. They all inherit many features from [[ref:libraries/vision2/reference/ev_widget_chart|EV_WIDGET]] . Each descendent of [[ref:libraries/vision2/reference/ev_primitive_chart|EV_PRIMITIVE]] will typically have many available features, specific to their type. For example, [[ref:libraries/vision2/reference/ev_separator_chart|EV_SEPARATOR]] has no extra features, but [[ref:libraries/vision2/reference/ev_label_chart|EV_LABEL]] has features for modifying the current font and also the text to be displayed.