Docs, api

TheDrawingCoder-Gamer · TheDrawingCoder-Gamer · commit 2f1392ad18f2 · 2023-03-13T00:25:48.000-04:00
diff --git a/docs/directory.conf b/docs/directory.conf
@@ -1,4 +1,5 @@
 laika.navigationOrder = [
 	index.md
 	concepts.md
+	gotchas.md
 ]
diff --git a/docs/gotchas.md b/docs/gotchas.md
@@ -0,0 +1,54 @@
+# Common Gotchas
+
+**Swing.IO** has a fundementally different base from **Calico**. While it tries to be similar, some **Calico**
+patterns are unsupported.
+
+```scala
+textField.withSelf { self =>
+  (
+    text <-- txtRef,
+    onValueChange --> {
+      _.foreach(_ => self.value.get.flatMap(txtRef.set))
+    }
+  )
+}
+```
+This pattern causes an infinite loop that consumes all memory in the app. 
+
+## Look And Feel
+When setting the Look and Feel of an app, Resources can't be prematurely initialized. 
+
+```scala
+for {
+  comp <- resourceComponent
+  win <- window(
+    lookAndFeel := ???,
+    // Don't do this, comp will be styled with the default look and feel
+    comp
+  )
+} yield win
+```
+
+Instead, obtain the resource directly. **Swing.IO** supports composing resources together, and it handles the 
+lifecycles itself. 
+
+```scala
+for {
+  comp = resourceComponent
+  win <- window(
+    lookAndFeel := ???,
+    comp
+  )
+} yield win
+```
+
+Look and feel can't be updated, as the components style won't update.
+
+## Circumventing DSL
+If you have to access a feature that isn't implemented in the DSL yet, you can use flatTaps.
+```scala
+checkbox(icon := ???).flatTap(_.iconTextGap.set(20).toResource)
+```
+## Adding custom components
+You can technically make your own component by extending a wrapper class. However, it requires wrapping a peer. WrappedRef is exposed to allow for wrapping.
+See source code for examples of wrapping.
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/AwtEventDispatchEC.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/AwtEventDispatchEC.scala
@@ -2,6 +2,10 @@ package net.bulbyvr.swing.io
 
 import scala.concurrent.ExecutionContext
 import javax.swing.SwingUtilities
+
+/**
+  * An ExecutionContext that executes on the AWT Event Dispatch thread
+  */
 object AwtEventDispatchEC extends ExecutionContext {
   def execute(r: Runnable): Unit = SwingUtilities.invokeLater(r)
   def reportFailure(t: Throwable): Unit = {
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/IOSwingApp.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/IOSwingApp.scala
@@ -5,6 +5,9 @@ import cats.effect.kernel.Resource
 import cats.effect.unsafe.implicits.*
 import cats.syntax.all.*
 trait IOSwingApp extends IOApp {
+  /**
+   * The MainFrame to be rendered
+   */
   def render: Resource[IO, (wrapper.MainFrame[IO], Deferred[IO, Unit])]
 
   def run(args: List[String]) = render.flatMap { case t @ (f, _) => Resource.make(f.open *> t.pure[IO])(_ => IO.unit) }.use { case (_, gate) => gate.get } *> ExitCode.Success.pure[IO] 
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/AbstractButton.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/AbstractButton.scala
@@ -13,7 +13,14 @@ abstract class AbstractButton[F[_]](dispatcher: Dispatcher[F], topic: Topic[F, e
   with WithIcon[F] { outer =>
   override lazy val peer: JAbstractButton = new JAbstractButton with SuperMixin {}
 
+  /**
+   * Trigger a click on this button
+   */
   def click: F[Unit] = F.delay { peer.doClick() }.evalOn(AwtEventDispatchEC)
+  /**
+   * Trigger a click with n clicks on this button
+   * @param n number of clicks
+   */
   def clickN(n: Int): F[Unit] = F.delay { peer.doClick(n) }.evalOn(AwtEventDispatchEC)
 
   lazy val a: ActionListener = _ => {
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/Adjustable.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/Adjustable.scala
@@ -33,8 +33,12 @@ object AdjustTo {
 }
 
 trait Adjusted[F[_]: Async] {
+  /**
+   * Orientation of a component
+   */
   def adjustTo: RefSource[F, AdjustTo]
 }
 trait Adjustable[F[_]: Async] extends Adjusted[F] {
+
   override def adjustTo: Ref[F, AdjustTo]
 }
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/ComboBox.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/ComboBox.scala
@@ -14,16 +14,33 @@ import java.awt.event.{ActionListener, ActionEvent}
 
 class ComboBox[F[_]: Async, A](dispatcher: Dispatcher[F], topic: Topic[F, event.Event[F]]) extends Component[F](topic, dispatcher) with WithRenderer[F, A] {
   override lazy val peer: JComboBox[A] = new JComboBox[A]() with SuperMixin
-  
+  /**
+   * Renderer
+   *
+   * Uses [[ListView.Renderer]] as java uses ListView under the hood.
+   */
   def renderer: RefSink[F, ListView.Renderer[F, A]] = WrappedSink(it => peer.setRenderer(it.peer))
 
+  /**
+   * The current selected index
+   */
   def index: Ref[F, Int] = new WrappedRef(peer.getSelectedIndex, peer.setSelectedIndex)
 
   // i love casting : (
+  /**
+   * Current selected item.
+   * WARNING: Setting will not work if the item isn't in the dropdown
+   */
   def item: Ref[F, A] = new WrappedRef(() => peer.getSelectedItem.asInstanceOf[A], peer.setSelectedItem)
 
+  /**
+   * Max row count that can be displayed without scrolling
+   */
   def maxRowCount: Ref[F, Int] = new WrappedRef(peer.getMaximumRowCount, peer.setMaximumRowCount)
 
+  /**
+   * Items in box. Write only access.
+   */
   def items: RefSink[F, Seq[A]] = WrappedSink { it => peer.removeAllItems(); it.foreach(peer.addItem) }
 
   private lazy val il: ActionListener = new ActionListener {
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/Component.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/Component.scala
@@ -16,6 +16,9 @@ abstract class Component[F[_]](topic: Topic[F, event.Event[F]], dispatcher: Disp
   trait SuperMixin {}
   // TODO: Support custom painting
   // Doing that requires wrapping Graphics2D which is kinda a lot
+  /**
+   * Name of component, for use with e.g. synth
+   */
   def name: Ref[F, String] =
     new WrappedRef(peer.getName, peer.setName)
   def xLayoutAlignment: Ref[F, Float] =
@@ -43,10 +46,20 @@ abstract class Component[F[_]](topic: Topic[F, event.Event[F]], dispatcher: Disp
 
   // TODO: Paint
   // Requires wrapping Graphics2D
+  /**
+   * Requests focus
+   */
   def requestFocus: F[Unit] =
     F.delay { peer.requestFocus() }.evalOn(AwtEventDispatchEC)
+  /**
+   * Request focus in the window this component is in
+   * @returns success
+   */
   def requestFocusInWindow: F[Boolean] =
     F.delay { peer.requestFocusInWindow() }.evalOn(AwtEventDispatchEC)
+  /**
+   * Revalidates this tree
+   */
   def revalidate: F[Unit] =
     F.delay { peer.revalidate() }.evalOn(AwtEventDispatchEC)
 
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/Container.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/Container.scala
@@ -4,6 +4,9 @@ package wrapper
 import cats.effect.Async
 
 trait Container[F[_]](using F: Async[F]) extends UIElement[F] {
+  /**
+   * Contents of this container. Read only.
+   */
   def contents: F[Seq[Component[F]]]
 }
 
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/FileChooser.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/FileChooser.scala
@@ -7,25 +7,25 @@ import java.io.File
 import cats.effect.syntax.all.*
 import cats.syntax.all.*
 object FileChooser {
-  private[io] class PartiallyAppliedApply[F[_]: Async] {
-    private def getFC: F[JFileChooser] =
+  final class PartiallyAppliedApply[F[_]] private[io] (val dummy: Boolean = true) extends AnyVal {
+    private def getFC(using Async[F]): F[JFileChooser] =
       Async[F].delay { JFileChooser() }.evalOn(AwtEventDispatchEC)
-    private def showDialog(show: JFileChooser => Int): F[(Int, JFileChooser)] = 
+    private def showDialog(show: JFileChooser => Int)(using Async[F]): F[(Int, JFileChooser)] = 
       getFC.flatMap { fc => 
         Async[F].delay { show(fc) }.evalOn(AwtEventDispatchEC).map { res =>
           (res, fc)
         }
       }
-    private def showOpenDialog(show: JFileChooser => Int): F[Option[File]] =
+    private def showOpenDialog(show: JFileChooser => Int)(using Async[F]): F[Option[File]] =
       showDialog(show).flatMap { (res, fc) =>
         if (res == JFileChooser.APPROVE_OPTION)
           Async[F].delay { Option(fc.getSelectedFile) }.evalOn(AwtEventDispatchEC)
         else
           None.pure[F]
 
       }
-    def save: F[Option[File]] = showOpenDialog(_.showSaveDialog(null))
-    def open: F[Option[File]] = showOpenDialog(_.showOpenDialog(null))
+    def save(using Async[F]): F[Option[File]] = showOpenDialog(_.showSaveDialog(null))
+    def open(using Async[F]): F[Option[File]] = showOpenDialog(_.showOpenDialog(null))
 
   }
   def apply[F[_]: Async]: PartiallyAppliedApply[F] = new PartiallyAppliedApply[F]
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/ListView.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/ListView.scala
@@ -88,8 +88,14 @@ object ListView {
   }
 }
 trait WithRenderer[F[_]: Async, A] {
+  /**
+   * Sets renderer. Write only access.
+   */
   def renderer: RefSink[F, ListView.Renderer[F, A]]
 }
+/**
+ * A view of a list of items represented as components with a renderer.
+ */
 class ListView[F[_]: Async, A](dispatcher: Dispatcher[F], topic: Topic[F, event.Event[F]]) extends Component[F](topic, dispatcher) with WithRenderer[F, A] {
   override lazy val peer: JList[A] = new JList[A]() with SuperMixin
   def ensureIndexIsVisible(idx: Int): F[Unit] =
@@ -109,6 +115,9 @@ class ListView[F[_]: Async, A](dispatcher: Dispatcher[F], topic: Topic[F, event.
     def getElementAt(n: Int): B = items(n)
     def getSize: Int = items.size
   }
+  /**
+   * The data in the list view.
+   */
   def listData: Ref[F, Seq[A]] =
     new WrappedRef(
       () => peer.getModel match {
@@ -126,6 +135,9 @@ class ListView[F[_]: Async, A](dispatcher: Dispatcher[F], topic: Topic[F, event.
       items => 
         peer.setModel(new ModelWrapper[A](items))
       )
+  /**
+   * Amount of rows visible without scrolling
+   */
   def visibleRowCount: Ref[F, Int] =
     new WrappedRef(peer.getVisibleRowCount, peer.setVisibleRowCount)
 
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/MutableContainer.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/MutableContainer.scala
@@ -4,6 +4,10 @@ package wrapper
 import cats.effect.Async
 import cats.syntax.all.*
 import cats.effect.syntax.all.*
+/**
+ * A container that makes sense for its contents to be mutable
+ * Usually for components that are sequential, like the Box and Flow panel
+ */
 trait MutableContainer[F[_]](using F: Async[F]) extends Container[F] {
   override def peer: javax.swing.JComponent
   override def contents: F[Seq[Component[F]]] =
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/WithChangableText.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/WithChangableText.scala
@@ -3,5 +3,12 @@ package wrapper
 import cats.effect.{Async, Ref}
 
 trait WithChangableText[F[_]](using F: Async[F]) {
+  /**
+   * Text stored in this instance
+   *
+   * What this data represents depends on the class. A text field 
+   * would represent the text inside the field, a label would be the
+   * label text, etc.
+   */
   def text: Ref[F, String]
 }
diff --git a/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/WithIcon.scala b/swingio/src/main/scala/net/bulbyvr/swing/io/wrapper/WithIcon.scala
@@ -21,6 +21,12 @@ class ImageIcon[F[_]](image0: Image[F])(using F: Async[F]) extends Icon[F] {
     new WrappedRef(peer.getDescription, peer.setDescription)
 }
 trait WithIcon[F[_]: Async] {
+  /**
+   * The current Icon, or None if there is no icon.
+   */
   def icon: Ref[F, Option[Icon[F]]]
+  /**
+   * Gap between any text and the icon
+   */
   def iconTextGap: Ref[F, Int]
 }

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`laika.navigationOrder = [`
`2`	`2`	`index.md`
`3`	`3`	`concepts.md`
	`4`	`+ gotchas.md`
`4`	`5`	`]`
Original file line number	Diff line number	Diff line change
`@@ -33,8 +33,12 @@ object AdjustTo {`
`33`	`33`	`}`
`34`	`34`
`35`	`35`	`trait Adjusted[F[_]: Async] {`
	`36`	`+ /**`
	`37`	`+ * Orientation of a component`
	`38`	`+ */`
`36`	`39`	`def adjustTo: RefSource[F, AdjustTo]`
`37`	`40`	`}`
`38`	`41`	`trait Adjustable[F[_]: Async] extends Adjusted[F] {`
	`42`	`+`
`39`	`43`	`override def adjustTo: Ref[F, AdjustTo]`
`40`	`44`	`}`
Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,9 @@ package wrapper`
`4`	`4`	`import cats.effect.Async`
`5`	`5`
`6`	`6`	`trait Container[F[_]](using F: Async[F]) extends UIElement[F] {`
	`7`	`+ /**`
	`8`	`+ * Contents of this container. Read only.`
	`9`	`+ */`
`7`	`10`	`def contents: F[Seq[Component[F]]]`
`8`	`11`	`}`
`9`	`12`