lib/app/ui.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #     http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 # Portable UI API for the _app.nit_ framework
  16 module ui
  17
  18 import app_base
  19
  20 redef class App
  21         super AppComponent
  22
  23         # The current `Window` of this activity
  24         #
  25         # This attribute must be set by refinements of `App`.
  26         var window: Window is writable
  27
  28         redef fun on_create do window.on_create
  29
  30         redef fun on_start do window.on_start
  31
  32         redef fun on_resume do window.on_resume
  33
  34         redef fun on_pause do window.on_pause
  35
  36         redef fun on_stop do window.on_stop
  37
  38         redef fun on_destroy do window.on_destroy
  39
  40         redef fun on_restore_state do window.on_restore_state
  41
  42         redef fun on_save_state do window.on_save_state
  43 end
  44
  45 # An event created by an `AppComponent` and sent to `AppObserver`s
  46 interface AppEvent
  47 end
  48
  49 # Observer of `AppEvent`s raised by `AppComponent`s
  50 interface AppObserver
  51         # Notification of `event` raised by `sender`
  52         #
  53         # To be implemented in subclasses as needed.
  54         fun on_event(event: AppEvent) do end
  55 end
  56
  57 redef class AppComponent
  58         super AppObserver
  59
  60         # All `AppObserver` notified of events raised by `self`
  61         #
  62         # By default, only `self` is an observer.
  63         # Any other `AppObserver` can be added to this collection.
  64         var observers = new HashSet[AppObserver].from([self: AppObserver])
  65
  66         # Propagate `event` to all `observers` by calling `AppObserver::on_event`
  67         fun notify_observers(event: AppEvent)
  68         do
  69                 for observer in observers do
  70                         observer.on_event(event)
  71                 end
  72         end
  73 end
  74
  75 # A control implementing the UI
  76 class Control
  77         super AppComponent
  78
  79         # Direct parent `Control` in the control tree
  80         #
  81         # If `null` then `self` is at the root of the tree, or not yet attached.
  82         var parent: nullable CompositeControl = null is private writable(set_parent)
  83
  84         # Direct parent `Control` in the control tree
  85         #
  86         # Setting `parent` calls `remove` on the old parent and `add` on the new one.
  87         fun parent=(parent: nullable CompositeControl)
  88         is autoinit     do
  89                 var old_parent = self.parent
  90                 if old_parent != null and old_parent != parent then
  91                         old_parent.remove self
  92                 end
  93
  94                 if parent != null then parent.add self
  95
  96                 set_parent parent
  97         end
  98 end
  99
 100 # A `Control` grouping other controls
 101 class CompositeControl
 102         super Control
 103
 104         private var items = new HashSet[Control]
 105
 106         # Add `item` as a child of `self`
 107         protected fun add(item: Control) do items.add item
 108
 109         # Remove `item` from `self`
 110         protected fun remove(item: Control) do if has(item) then items.remove item
 111
 112         # Is `item` in `self`?
 113         protected fun has(item: Control): Bool do return items.has(item)
 114
 115         redef fun on_create do for i in items do i.on_create
 116
 117         redef fun on_start do for i in items do i.on_start
 118
 119         redef fun on_resume do for i in items do i.on_resume
 120
 121         redef fun on_pause do for i in items do i.on_pause
 122
 123         redef fun on_stop do for i in items do i.on_stop
 124
 125         redef fun on_destroy do for i in items do i.on_destroy
 126
 127         redef fun on_restore_state do for i in items do i.on_restore_state
 128
 129         redef fun on_save_state do for i in items do i.on_save_state
 130 end
 131
 132 # A window, root of the `Control` tree
 133 class Window
 134         super CompositeControl
 135 end
 136
 137 # A viewable `Control`
 138 abstract class View
 139         super Control
 140
 141         # Is this control enabled so the user can interact with it?
 142         #
 143         # By default, or if set to `null`, the control is enabled.
 144         var enabled: nullable Bool is writable #, abstract FIXME with #1311
 145 end
 146
 147 # A control with some `text`
 148 abstract class TextView
 149         super View
 150
 151         # Main `Text` of this control
 152         #
 153         # By default, or if set to `null`, no text is shown.
 154         var text: nullable Text is writable #, abstract FIXME with #1311
 155 end
 156
 157 # A control for the user to enter custom `text`
 158 class TextInput
 159         super TextView
 160 end
 161
 162 # A pushable button, raises `ButtonPressEvent`
 163 class Button
 164         super TextView
 165 end
 166
 167 # A `Button` press event
 168 class ButtonPressEvent
 169         super AppEvent
 170
 171         # The `Button` that raised this event
 172         var sender: Button
 173 end
 174
 175 # A layout to visually organize `Control`s
 176 abstract class Layout
 177         super View
 178         super CompositeControl
 179 end
 180
 181 # An horizontal linear organization
 182 class HorizontalLayout
 183         super Layout
 184 end
 185
 186 # A vertical linear organization
 187 class VerticalLayout
 188         super Layout
 189 end