smouldering-beach-ball

9 Using Smouldering Beach Ball in Your Project

Although there are slight variations, you will use SmoulderingBeachBall (S.B.B.) as a three-step process. They are as follows:

Construct a specification, declaring how you want your image to look.
Pass the specification to S.B.B. so it knows how you want the final image to look.
Tell S.B.B. to make the image -- either synchronously or asynchronously.

For now, I will not go into detail on what the specifications look like. Instead, I will provide an example of the steps above in code. You can ignore the try-with block and the function definition for now -- I kept it in for extra context.

let ``draw-image`` imgWidth imgHeight mainColour oColour oType path =
	try
            // Assume "buildSpec" is the abstracted version of step 1 above.
	    buildSpec imgWidth imgHeight mainColour oColour oType path
            |> makeImage
	    |> Async.RunSynchronously
	with
	| :? ArgumentException as ex -> ex.Message
	| _ as ex -> ex.Message

For more in-depth examples, have a look at "ConsoleCommands.fs". In here, you will find "real world" examples of this library in use.The links for that is as follows:

ConsoleCommands.fs

You can view the code for the various specifications using the following link:

Domain.fs

The Pieces you will be Working With

As a consumer of S.B.B., you will not have access to every part it. Instead, you will work within two name-spaces: SmoulderingBeachBall.Domain and SmoulderingBeachBall. With that said, the module in Domain utilises the AutoOpen attribute. This means you only need to add open SmoulderingBeachBall.Service to start using it (Service is the module you use which resides in SmoulderingBeachBall).

IMAGE OF PARTS YOU USE.

Because SmoulderingBeachBall.Domain automatically opens, you might get a false impression about the main component you will use. You might think the ServicesSmoulderingBeachBall.Service module is where you will spend most of your time. This is a red herring. The reason why is because Service does only one thing: make the Image. Granted, it is a two-step process, which is "make image" and "save/commit/write image". But, they are practically two sides of the same coin. To help demonstrate that, please consider the following code:

makeImage yourSpec
|> Async.Run // Or, Async.RunSynchronously

Once you have those two lines in the memory bank, you will spend most of your time in Domain. This is because, to put it simply, there is more to work with.

Public A.P.I.

The template is as follows:

Name

Parameters
Description
Usage/Examples

`makeImage`

(spec: ImageSpec)
An asynchronous function which creates an image using the specification provided by the ImageSpec data-type.

(* Example 1: Create a spec and pass it into the makeImage function.
==================================================================== *)

// Create your spec in another function...
|> makeImage
|> Async.Run

(* Example 2: Create a spec (with no overlay) at the same time you
call the makeImage function.
==================================================================== *)

{ width = 500
  height = 500
  colour = Brush.AntiqueWhite
  filePath = "C:/path/to/save/at"
  overlay = None
}
|> makeImage
|> Async.Run

(* Example 3: Create a spec (with A full overlay) at the same time
you call the makeImage function.
==================================================================== *)

let fullOverlay =
    { colour = Brush.Black
	  overlayType = Full }

{ width = 500
  height = 500
  colour = Brush.AntiqueWhite
  filePath = "C:/path/to/save/at"
  overlay = some (fullOverlay)
}
|> makeImage
|> Async.Run

(* Example 4: Create a spec (with A border overlay) at the same time
you call the makeImage function.
=====================================================================*)

let borderOverlay =
    { colour = Brush.Red
	  overlayType = Border }

{ width = 500
  height = 500
  colour = Brush.AntiqueWhite
  filePath = "C:/path/to/save/at"
  overlay = some (borderOverlay)
}
|> makeImage
|> Async.Run

(* Example 5: The verbose example.
=====================================================================*)

let borderOverlay =
    { colour = Brush.Pink
	  overlayType = Border }

let spec =
    { width = 500
      height = 500
      colour = Brush.AntiqueWhite
      filePath = "C:/path/to/save/at"
      overlay = some (borderOverlay)
    }

spec
|> makeImage
|> Async.Run

// or...

makeImage spec
|> Async.Run

The Pieces you will be Working With

Public A.P.I.

Name

`makeImage`

Table of Contents

As Source Code

SmoulderingBeachBall

SmoulderingBeachBallCLI

TestCentre

As a Command-Line Interface (C.L.I)

As a NuGet