Skip to content

Commit

Permalink
Add some documentation on events.
Browse files Browse the repository at this point in the history
  • Loading branch information
@io7m
io7m committed Dec 8, 2023
1 parent 5a83e17 commit e826efc
Show file tree
Hide file tree
Showing 3 changed files with 142 additions and 12 deletions.
65 changes: 62 additions & 3 deletions ...m.jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-event.xml
View file
Expand Up @@ -4,8 +4,67 @@
id="bcc3c7a6-df1c-4dc8-8263-2364630db64a"
title="Events">

<Paragraph>
An event...
</Paragraph>
<Subsection title="Description">
<Paragraph>
<Term type="term">Events</Term>
are the primary means by which the
<Term type="package">jsycamore</Term>
package accepts input from external code, and by which it publishes notifications on state changes.
</Paragraph>
<Paragraph>
Events are divided into <Link target="faf14bf9-408c-4e98-a380-37abfc5b6271">input events</Link> and
<Link target="cc1c3bb7-e1e4-41ce-86c1-e52cb4f261d6">output events</Link>.
</Paragraph>
</Subsection>

<Subsection title="Input Events"
id="faf14bf9-408c-4e98-a380-37abfc5b6271">
<Subsection title="Description">
<Paragraph>
<Term type="term">Input events</Term>
are events that represent input to the UI. In order to remain fully platform-independent, the
<Term type="package">jsycamore</Term>
package does not directly read from the keyboard and mouse. Instead, users are expected to be running
<Term type="package">jsycamore</Term>
inside an existing system such as
<LinkExternal target="https://en.wikipedia.org/wiki/Abstract_Window_Toolkit">AWT</LinkExternal>, or perhaps
embedded in a GPU context via
<LinkExternal target="https://www.glfw.org/">GLFW</LinkExternal>, and are therefore responsible for translating
input events coming from those systems into method calls defined on the
<Term type="class">SyScreenMouseEventsType</Term>
and
<Term type="class">SyScreenKeyEventsType</Term>
interfaces. When these methods are called, the screen will
<Link target="b097067b-b8d6-4397-bb24-6a48f003e84f">dispatch</Link>
input events internally to any relevant
<Link target="0c480fad-ee66-4532-a0b1-f06ebe582ea8">components</Link>.
</Paragraph>
</Subsection>

<Subsection title="Mouse Events" id="ef6bcdaf-a8e3-4752-9744-d6221601262f">
<Paragraph>
Mouse events...
</Paragraph>
</Subsection>

<Subsection title="Keyboard Events" id="c94f6a20-0543-4da3-bf60-9a1dea6eaeed">
<Paragraph>
Keyboard events...
</Paragraph>
</Subsection>
</Subsection>

<Subsection title="Output Events"
id="cc1c3bb7-e1e4-41ce-86c1-e52cb4f261d6">
<Paragraph>
<Term type="term">Output events</Term>
are events that indicate state changes that have occurred. For example, closing a window will publish
an <Link target="29c70488-7d76-4091-9f7e-c6d4a6c66476">event</Link>.
</Paragraph>
<Paragraph>
Users may obtain access to a stream of output events from each
<Link target="03b8a907-42cf-47b1-a72b-4ba9a90a77ae">screen</Link>.
</Paragraph>
</Subsection>

</Section>
87 changes: 79 additions & 8 deletions ....jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-screen.xml
View file
Expand Up @@ -57,14 +57,85 @@
</FormalItem>
</Subsection>

<Subsection title="Events">
<Paragraph>
A screen provides an
<LinkExternal
target="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/concurrent/Flow.Publisher.html">
observable stream</LinkExternal> of <Link target="bcc3c7a6-df1c-4dc8-8263-2364630db64a">events</Link>
to which external code may subscribe.
</Paragraph>
<Subsection title="Events" id="03b8a907-42cf-47b1-a72b-4ba9a90a77ae">
<Subsection title="Output Events">
<Paragraph>
A screen provides an
<LinkExternal
target="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/concurrent/Flow.Publisher.html">
observable stream</LinkExternal> of <Link target="cc1c3bb7-e1e4-41ce-86c1-e52cb4f261d6">output events</Link>
to which external code may subscribe.
</Paragraph>
</Subsection>
<Subsection title="Input Event Dispatch" id="b097067b-b8d6-4397-bb24-6a48f003e84f">
<Subsection title="Description">
<Paragraph>
When any of the methods on the
<Term type="class">SyScreenMouseEventsType</Term>
and
<Term type="class">SyScreenKeyEventsType</Term>
interfaces are called, the screen will dispatch appropriate events to
<Link target="0c480fad-ee66-4532-a0b1-f06ebe582ea8">components</Link>
inside
<Link target="cb46abcd-d0b1-41f4-bb95-662186d4aa78">windows</Link>
that are visible on the screen.
</Paragraph>
</Subsection>
<Subsection title="Mouse Events">
<Paragraph>
When dispatching <Link target="ef6bcdaf-a8e3-4752-9744-d6221601262f">mouse events</Link>, the process
is as follows for an arbitrary mouse event <Term type="variable">e</Term>:
</Paragraph>
<FormalItem title="Mouse Event Dispatch">
<ListOrdered>
<Item>
Get a list of the visible <Link target="cb46abcd-d0b1-41f4-bb95-662186d4aa78">windows</Link> in
<Link target="caab0ac3-f623-457f-986d-312b260f184e">order</Link> such that the frontmost windows
are at the start of the list, and the rearmost windows are at the end of the list.
</Item>
<Item>
For each window <Term type="variable">w</Term> in the list of visible windows:
<ListOrdered>
<Item>
If the <Link target="7973aa4f-4fd9-40dd-8d96-0aaa3b4d6147">viewport-space</Link> position
of the mouse event (the cursor position) falls within the viewport-space bounds of
<Term type="variable">w</Term>, then ask <Term type="variable">w</Term> for the
<Link target="0c480fad-ee66-4532-a0b1-f06ebe582ea8">component</Link>
<Term type="variable">c</Term> that is overlapped by the cursor. The window implementation
is required to return the most specific component for the given position; the component that
is deepest within the tree of components for the given position. If there is no
appropriate <Term type="variable">c</Term>, then continue on to the next window.
</Item>
<Item>
Assuming there was an existing component <Term type="variable">c</Term>,
call the <Term type="function">eventSend</Term> method on <Term type="variable">c</Term>, passing
it the event <Term type="variable">e</Term>. The method will return a value that indicates
whether the component <Term type="term">consumed</Term> the event. If the event was consumed,
execution stops here. Otherwise, if the event was not consumed, then the
<Term type="function">eventSend</Term> method is called on each recursively selected ancestor
of <Term type="variable">c</Term> until either one of the ancestors consumes the event, or
there are no more ancestors. If the event is consumed, execution stops here. If there are
no more ancestors, we return to the first step and try the next visible window.
</Item>
<Item>
If no component in any of the examined windows consumes <Term type="variable">e</Term>, then
<Term type="variable">e</Term> is discarded.
</Item>
</ListOrdered>
</Item>
</ListOrdered>
</FormalItem>
<Paragraph>
Typically, successfully dispatching a mouse event to a window will result in that window
becoming <Link target="caab0ac3-f623-457f-986d-312b260f184e">focused</Link>.
</Paragraph>
</Subsection>
<Subsection title="Keyboard Events">
<Paragraph>
Keyboard events...
</Paragraph>
</Subsection>
</Subsection>
</Subsection>

<Subsection title="Theme">
Expand Down
2 changes: 1 addition & 1 deletion ....jsycamore.documentation/src/main/resources/com/io7m/jsycamore/documentation/m-window.xml
View file
Expand Up @@ -143,7 +143,7 @@
</ListUnordered>
</FormalItem>
</Subsection>
<Subsection title="Events">
<Subsection title="Events" id="29c70488-7d76-4091-9f7e-c6d4a6c66476">
<Paragraph>
When a window is closed, an event of type <Term type="type">SyWindowClosed</Term> will be published.
</Paragraph>
Expand Down

0 comments on commit e826efc

Please sign in to comment.