Add docs section on how to use when_imagej_starts

This commit adds section 5.2 to the "Convenience methods of
PyImageJ" that describes how to use the when_image_starts
callback mechanism.

conftest.py

@@ -43,7 +43,9 @@ def ij(request):
     legacy = request.config.getoption("--legacy")
     headless = request.config.getoption("--headless")
 
-    imagej.when_imagej_starts(lambda ij: setattr(ij, "_when_imagej_starts_result", "success"))
+    imagej.when_imagej_starts(
+        lambda ij: setattr(ij, "_when_imagej_starts_result", "success")
+    )
 
     mode = "headless" if headless else "interactive"
     ij = imagej.init(ij_dir, mode=mode, add_legacy=legacy)

doc/05-Convenience-methods-of-PyImageJ.ipynb

@@ -129,6 +129,31 @@
    "source": [
     "Note the warnings! We're currently in headless mode. The many legacy ImageJ functions operate limitedly or not at all in headless mode. For example the `RoiManager` is not functional in a true headless enviornment."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5.2 Register functions to start with ImageJ\n",
+    "\n",
+    "Functions can be executed during ImageJ's initialization routine by registering the functions with PyImageJ's callback mechanism `when_imagej_starts()`. This is particularly useful for macOS users in `gui` mode, allowing functions to be called before the Python [REPL/interpreter](https://docs.python.org/3/tutorial/interpreter.html) is [blocked](Initialization.md/#gui-mode).\n",
+    "\n",
+    "The following example uses `when_imagej_starts()` callback display a to `uint16` 2D NumPy array it with ImageJ's viewer, print it's dimensions (_i.e._ shape) and open the `RoiManager` while ImageJ initializes.\n",
+    "\n",
+    "```python\n",
+    "import imagej\n",
+    "import numpy as np\n",
+    "\n",
+    "# register functions\n",
+    "arr = np.random.randint(0, 2**16, size=(256, 256), dtype=np.uint16) # create random 16-bit array\n",
+    "imagej.when_imagej_starts(lambda ij: ij.RoiManager.getRoiManager()) # open the RoiManager\n",
+    "imagej.when_imagej_starts(lambda ij: ij.ui().show(ij.py.to_dataset(arr))) # convert and display the array\n",
+    "imagej.when_imagej_starts(lambda _: print(f\"array shape: {arr.shape}\"))\n",
+    "\n",
+    "# initialize imagej\n",
+    "ij = imagej.init(mode='interactive')\n",
+    "```"
+   ]
   }
  ],
  "metadata": {