Skip to content

ccWiki

Jump to bottom
yokiano edited this page Jun 7, 2020 · 3 revisions

Welcome to the Code Controller library wiki!

The below topics will guide you through all of the different control types and features that you need to be aware of.

Table of Contents:

Prerequisites
Controllers
Dynamic Label and Plotter
Additional Features

Value Registry
Remove and Refactor
Fast Layout

Prerequisites

Installation

Before the fun begins you will need to include the code controller library in your project. The easiest way to do it is using Gradle which involves copying and pasting of only few lines of code.

Using gradle with kotlin script (build.gradle.kts file):

repositories {
	// …
  jcenter()	// <- needed due to internal dependencies
  maven(url = "https://dl.bintray.com/yokiano/my-tools")
}

dependencies {
	// ...
  implementation("yokiano","code-controller", "0.0.1")
}

Using gradle with groovy script (build.gradle file):

repositories {
	// …
  jcenter()	// <- needed due to internal dependencies
  maven url = ‘https://dl.bintray.com/yokiano/my-tools’
}

dependencies {
	// ...
  implementation ‘yokiano:code-controller:0.0.1’
}

If you are not using gradle, the jar file is available for manual download from Bintray repository, just make sure to use the latest version.

Extending your class

The preferred way to use the code controller API is to extend the class that you are working on with the helper class CCAware. After doing so you can freely use any of the API functions in that class including extension functions for the different types (Numbers,Boolean,Double Pair).

class MyClass : CCAware {
   val someNumber1 = ccDouble("first slider")
   val someNumber2 = 10.0.ccDouble("second slider") // will create a slider with 10.0 as the default value. 
}

If you are not able to extend your class, you can invoke the basic API functions by referring to the CodeController object (kotlin singleton).

fun main() {
  val someNumber = CodeController.ccDouble("some slider")
}

*for simplicity sake, in the rest of the wiki we will assume the CCAware method is used.

Controllers:

The format of a controller declaration -
ccType("ID",<optional args>) { configuration block }
A declaration of a gui controller consists of the following parts - (1) the controller type function, e.g ccDouble. (2) the ID (String) of the controller which is the first function argument. each ID and type combination represents a single controller. (3) Optional arguments like 'range', 'default' etc. (4) An optional configuration block which is an alternative to the optional arguments.

*In case the CC panel is inactive (Can be disabled from the power button in top left corner), returned value will be the default value.

  1. Slider - ccDouble()

    1. Returns a Double value between the defined range.
    2. Arguments:
      1. id: String (required)
      2. default: Double (optional). if not specified the default value is 0.0 .
      3. range: ClosedFloatingPointRange (optional). if not specified the default range is 0.0..1.0
    3. Configuration Parameters exposed:
      1. range: ClosedFloatingPointRange - determines the slider range.
      2. default: Double - determines the initial value on startup (in case no value is already saved in value registry , explained in the value registry section)
    4. Full example and use case: 
         val circleRadius = ccDouble("radius slider") {  
   range = 3.0..10.0 
   default = 5.8
   } // example using the configuration block
   val circleOffset = 400.0.ccDouble("offset slider",range = 0.0..800.0) // example using extension function + defining range in the function arguments.
   magicallyCreateACircle(radius = someNumber)
   moveCircle(circleOffset)

  2. Toggle - ccBool()

    1. Returns a Boolean value according to the toggle button state
    2. Arguments:
      1. id: String (required)
      2. default: Boolean (optional). if not specified default will be true.
    3. Configuration Parameters exposed
      1. default: Boolean - determines the initial value on startup (in case no value is already saved in the value registry file, explained in the value registry section)
    4. Full example and use case: 
         if (ccBool("Decide If",true)) {
      // Do something
   }

  3. XY Controller (2D Vector) - ccVec2()

    1. Returns a kotlin Pair type according to the controller X/Y coordinates.

    2. Arguments:

      1. id: String (required)
      2. default: Pair<Double,Double> (optional). if not specified default will be Pair(0.0,0.0).
      3. range: Pair<Pair<Double,Double>,Pair<Double,Double>>

    3. Configuration Parameters/Methods exposed

      1. default (Pair<Double,Double>) - determines the initial value on startup (in case no value is already saved in value registry file, explained in the value registry section)
      2. setRange(xMin: Double, yMin: Double, xMax: Double, yMax: Double) - determines the most left top and right bottom corner values.

    4. Full example and use case:

      ccVec2("element position") {  
   setRange(1.0,0.0,6.0,2.0)  
   default = Pair(1.0,0.0)
}.apply {  
    placeYourElementAt(this.first,this.second)
}

Dynamic Label and Plotter

Code Controller includes two additional tools to help debugging and understanding your software behavior - XY-Plotter and Dynmic label.

Dynamic Label: ccInfo()

Easily display the value of a variable or expression in a "live" manner, the value is updated each time the ccInfo() function is called.
Usage - ccInfo("Label Title", "${SomeVariable}")
Note: The ID should be unique. Declaring 2 different labels with the same ID will create overrides between the 2 labels.

Plotter: ccPlot()

Instantly creates a simple XY-line-chart that plots a desired XY coordinate.
Basic Usage -

ccPlot("line title",xValue, yValue)  // (supported value type is only Double at the moment)

To limit the amount of visible data points you can use the howMany argument. for example howMany = 100 will result that only the last 100 data points will be visible in the line chart.
howMany Usage Example:

ccPlot("only last 100", seconds, magnitude, howMany = 100)

Note:
Sometimes the interval between function calls to ccPlot() or CCinfo() is too short and can cause the dynamic label value to flicker too fast or the to plotter line chart to be overwhelmed with data points so it is not readable. In those cases, you can use an argument named reduceCalls, that will take a number between 0 to 1 and will use probability to reduce the amount of function calls that actually counts as "real".
Usage Example:

ccInfo("label title", "${someExpression}" , reduceCalls = 0.8)
ccPlot("line title", xValue, yValue, howMany = 150, reduceCalls = 0.8)

The above example will reduce/disregard 80% of the function calls to ccInfo and ccPlot.

Additional Features

Value Registry

The value registry let's you to save the value of each of the displayed controllers to a local registry so when you are restarting your program (and with it the cc panel), the saved value will be present on startup.
Currently the value registry allows 3 operations and all are accessible through right click on any of the active controllers:

  • Save Value: The registry key is a combination of the controller type and the ID of that controller.
  • Load Value: Will instantly change the value of the controller to the saved value.
  • Delete Saved Value: Will remove the value associated with the controller, if exists.

Remove and Refactor

Currently an experimental feature, but can improve your user experience dramatically if used correctly and with care. It's accessible through right clicking on any controller. Once clicked it will remove the controller gui element from the cc panel and will also replace all of the controller declarations (e.g "ccDouble("remove me later")" ) in your program's source code with the currently applied value.
Important - as we are aware that any source code refactoring is a terrifying and potentially destructive operation, any file that is changed through this process will be backed up and saved prior to the refactor. The backup files will be placed in a folder named ccBackup under the same directory of the refactored file.

Fast Layout

Due to the (intended) lack of layout flexibility and Because the cc panel is an additional window that can include several panes, you might want to move the panel around and resize those panes quite frequently. Therefore we tried to make the interaction with the layout as productive as possible. And because it was fun too.
These are your options:

  • Right click anywhere and drag: will move the cc panel around.
  • Middle click and drag: Used to resize the whole cc panel. It will effect the closest edge to the initial mouse click.
  • Left click and drag on a pane: Will resize only that pane. if the most left and right edges are clicked, it will have similar effect as the Middle button (resize the cc panel).
Clone this wiki locally